Polish Academic MCP

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.2
Disambiguation3/5
The tool set covers many distinct Polish academic resources, but there is significant overlap in functionality across different repositories (e.g., multiple '*_search' and '*_get_item' tools for different universities). While each tool is tied to a specific source, an agent could easily confuse similar tools like 'agh_search' and 'amu_search' since they perform identical operations on different repositories. The descriptions help differentiate them, but the sheer number of similar tools creates ambiguity.
Naming Consistency4/5
Most tools follow a consistent 'prefix_verb_noun' naming pattern (e.g., 'agh_search', 'bdl_get_variable', 'saos_dump_judgments'), which is predictable and readable. There are minor deviations, such as 'polon_search' lacking a prefix and 'wolnelektury_filter_books' using a longer prefix, but overall the naming is coherent and follows a clear convention across the set.
Tool Count2/5
With 85 tools, the count is excessive for a single server, making it overwhelming and difficult to navigate. While the server aims to cover many Polish academic resources, the tools could be consolidated (e.g., generic repository search/get tools with parameters) rather than having separate tools for each institution. This bloated count reduces usability and coherence.
Completeness4/5
The tool set provides broad coverage of Polish academic domains, including repositories, legal sources, statistical data, and cultural archives. Most areas offer search and retrieval capabilities, with few obvious gaps. However, some tools lack update or delete operations (e.g., no tools to modify data), but this is reasonable given the read-only nature of many public APIs. Overall, the surface is comprehensive for its intended purpose.
Average 4/5 across 85 of 85 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the return format ('raw JSON') but doesn't disclose other behavioral traits like error handling, rate limits, authentication needs, or whether it's a read-only operation. This is inadequate for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the purpose and return format without unnecessary details. It could be slightly improved by front-loading key information more explicitly, but it's generally well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic action and return format but lacks details on usage guidelines and behavioral transparency, which are needed for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 the 'listing_id' parameter fully. The description adds no additional meaning beyond what the schema provides, such as examples or constraints, resulting in the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and resource ('one source (listing) by numeric WordPress post ID from Baza Legalnych Źródeł'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'blz_search' or 'blz_listing_categories', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'blz_search' or other sibling tools. It mentions the resource but lacks context about prerequisites, timing, or comparisons, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the HTTP method (POST) and return type (JSON MetadataDTO), but lacks details on rate limits, error handling, pagination behavior beyond parameters, or whether it's read-only/destructive. This is insufficient for a search tool with authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. It could be slightly more structured (e.g., separating authentication from return details), but it avoids redundancy and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with authentication needs and no output schema, the description is incomplete. It doesn't explain the return format (MetadataDTO structure), error cases, or how results are ordered/filtered. Given the complexity and lack of annotations, more behavioral context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds no additional parameter semantics beyond implying search via first/last name, ORCID, or object ID, which is already clear from the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search persons') and target resource ('in PBN'), specifying it searches for researchers via ORCID. However, it doesn't explicitly differentiate from sibling tools like 'pbn_search_publications' or other search tools, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions authentication requirements ('Requires PBN_APP_ID and PBN_APP_TOKEN') but provides no guidance on when to use this tool versus alternatives (e.g., other PBN tools or general search tools in the sibling list). There's no mention of prerequisites, exclusions, or comparative use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the HTTP method (GET) and endpoint structure, which implies a read-only operation, but doesn't explicitly state this or discuss other behavioral aspects like rate limits, authentication requirements, error conditions, or what the response format looks like. The description provides basic operational context but misses important behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise with two sentences that cover the core functionality and API details. The first sentence clearly states what the tool does, and the second provides technical implementation context. There's no unnecessary verbiage, though the API endpoint detail might be more technical than needed for an AI agent's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what the tool returns (data format, structure), doesn't mention error handling or constraints beyond the basic parameter requirements, and doesn't provide context about the data domain or typical use cases. The API endpoint reference is helpful but doesn't compensate for the missing behavioral and output information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all 7 parameters thoroughly. The description adds minimal value by mentioning 'Optional year list and paging' which corresponds to 'years', 'page', and 'page_size' parameters, but doesn't provide additional semantic context beyond what's in the schema descriptions. This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch values') and target ('for one territorial unit for one or more variables'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'bdl_get_data_by_variable' or 'bdl_get_variable', which appear to be related data-fetching tools in the same domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context by stating 'Requires at least one variable id' and mentioning optional parameters, but it doesn't explicitly guide when to use this tool versus alternatives like 'bdl_get_data_by_variable'. The API endpoint reference adds technical context but not comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions pagination, which is useful, but lacks details on authentication needs, rate limits, error handling, or what the output looks like (e.g., format of enrichment tags). For a tool with no annotations, this leaves significant gaps in understanding its operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads key information: 'SAOS dump: paginated list of enrichment tags from the SAOS enrichment module (labels for judgments).' It avoids redundancy and waste, clearly stating the tool's core function without unnecessary elaboration. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no nested objects) and 100% schema coverage, the description is adequate but incomplete. It lacks output schema information, which isn't required to explain return values, but with no annotations, it should provide more behavioral context (e.g., what the list contains, any limitations). It meets minimum viability but has clear gaps in transparency and guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear documentation for page_size and page_number. The description adds no additional parameter semantics beyond implying pagination, which is already evident from the schema. According to the rules, with high schema coverage (>80%), the baseline score is 3, as the schema does the heavy lifting and the description doesn't compensate with extra insights.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'paginated list of enrichment tags from the SAOS enrichment module (labels for judgments).' It specifies the verb ('paginated list'), resource ('enrichment tags'), and source ('SAOS enrichment module'), distinguishing it from other SAOS tools like saos_dump_judgments or saos_search_judgments. However, it doesn't explicitly differentiate from all siblings, such as saos_dump_common_courts, which may have similar paginated list functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over other SAOS tools like saos_search_judgments or saos_get_judgment, nor does it specify prerequisites or exclusions. The agent must infer usage from the tool name and description alone, which is insufficient for optimal selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions pagination, which is useful, but doesn't describe what the list contains (e.g., fields, structure), how results are ordered, error handling, or any constraints like rate limits or authentication needs. For a list tool with no annotations, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads key information (SAOS dump, paginated list, resource). There's no wasted text, and it's appropriately sized for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no annotations, no output schema), the description is minimally adequate. It covers the basic purpose and pagination but lacks details on output format, usage context, and behavioral traits. For a list tool, this is acceptable but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters (page_size and page_number). The description adds no additional parameter semantics beyond what's in the schema, such as explaining what 'chambers and divisions' means in the context of pagination. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as a 'paginated list of Supreme Court chambers and divisions,' specifying both the action (list) and resource (chambers/divisions). It distinguishes from many siblings by focusing on SAOS and chambers/divisions, though it doesn't explicitly differentiate from 'saos_dump_common_courts' or other SAOS dump tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention when this tool is appropriate, what it's for, or how it differs from other SAOS tools like 'saos_dump_common_courts' or 'saos_dump_judgments.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool 'Returns HTML' and mentions pagination indirectly via the parameter list, but doesn't describe important behavioral aspects like whether this is a read-only operation, potential rate limits, authentication needs, error conditions, or what the HTML output contains. The description adds minimal behavioral context beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose in the first sentence. The domain ID list is necessary but lengthy; however, it's structured clearly. No wasted sentences, though the HTML return statement could be integrated more smoothly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter tool with no annotations and no output schema, the description provides adequate basic information about what the tool does and the domain options. However, it lacks details about the HTML output format, error handling, and comparison with sibling tools. The completeness is minimal but viable given the tool's apparent simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds value by providing the complete list of domain IDs with their names (24-42), which gives semantic meaning beyond the schema's 'Subject domain id (24–42)'. However, it doesn't add information about the 'page' parameter beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Browse BazTOL by subject domain' with the specific resource being 'BazTOL' and action being 'browse'. It distinguishes from sibling tools like 'baztol_search' by focusing on domain-based browsing rather than keyword searching. However, it doesn't explicitly mention what 'BazTOL' is (though context suggests a resource collection).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning 'same categories as the portal sidebar' and listing domain IDs, suggesting this tool is for domain-specific exploration. However, it doesn't explicitly state when to use this versus alternatives like 'baztol_search' or 'baztol_get_resource', nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the data format (WordPress REST JSON) but lacks critical behavioral details: it does not specify if this is a read-only operation, potential error conditions (e.g., invalid page_id), rate limits, authentication needs, or what the output looks like. The description is minimal and leaves key operational aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It is front-loaded with the core action and resource, and every part (fetch, static page, source, format, endpoint) contributes essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It does not cover behavioral aspects like safety (read-only vs. mutation), error handling, or output structure, which are crucial for a tool with no structured metadata. While concise, it fails to provide sufficient context for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'page_id' documented as 'Numeric page id from nac_site_search'. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. However, with high schema coverage, the baseline is 3, as the schema adequately describes the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch'), the resource ('a single static page'), the source ('from nac.gov.pl'), and the format ('as WordPress REST JSON'). It also distinguishes from sibling tools by specifying the exact API endpoint ('/wp/v2/pages/{id}'), making it distinct from generic search or other page-fetching tools in the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing a page_id from nac_site_search, which is only implied by the parameter description), nor does it differentiate from similar tools like nac_get_post or other get_item tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about authentication requirements and the endpoint path (GET /v1/publications/id/{id}), which helps the agent understand operational constraints. However, it doesn't describe response format, error handling, rate limits, or whether this is a read-only operation (though 'Fetch' implies reading).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences that each serve a clear purpose: stating the tool's function and specifying authentication requirements. It's front-loaded with the core purpose. There's minimal waste, though it could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 1 parameter with full schema coverage but no annotations and no output schema, the description provides adequate but incomplete context. It covers authentication and endpoint details but lacks information about return values, error cases, or how this differs from sibling tools. For a simple lookup tool, this is minimally viable but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single parameter. The description doesn't add any meaningful parameter semantics beyond what's in the schema (which explains it's a 'Publication object id from search results'). Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch extended publication metadata') and resource ('by PBN Mongo object id'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'pbn_search_publications' or 'pbn_search_persons', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions authentication requirements ('Requires PBN_APP_ID and PBN_APP_TOKEN') but provides no guidance on when to use this tool versus alternatives like 'pbn_search_publications' or other publication-related tools. There's no explicit when/when-not context or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions authentication requirements ('Requires PBN_APP_ID and PBN_APP_TOKEN') and the return format ('Returns JSON (MetadataDTO)'), which adds useful context. However, it doesn't describe pagination behavior, rate limits, error handling, or whether this is a read-only operation, leaving significant gaps for a search tool with 12 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: one stating the purpose and endpoint, another listing filter capabilities. It's appropriately sized with no redundant information. However, it could be slightly more front-loaded by moving the filter list to a separate line for better scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters, search functionality) and lack of both annotations and output schema, the description is moderately complete. It covers authentication, return format, and filterable fields, but doesn't explain the response structure (MetadataDTO), pagination behavior, or error cases. For a search tool without output schema, more detail about expected results would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 thoroughly. The description lists filterable fields ('Filter by title, DOI, ISBN, ISSN, year range, type, authors, pagination') which aligns with the schema but adds minimal semantic value beyond what's already in parameter descriptions. The baseline score of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search publications in Polska Bibliografia Naukowa (PBN)'. It specifies the verb ('Search') and resource ('publications'), and mentions the target system (PBN). However, it doesn't explicitly differentiate from sibling tools like 'pbn_search_persons' or 'pbn_get_publication', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'pbn_search_persons' for searching authors or 'pbn_get_publication' for retrieving specific publications, nor does it specify prerequisites beyond authentication requirements. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the output format ('Raw JSON from WordPress REST') but doesn't disclose behavioral traits like pagination behavior (implied by parameters but not described), rate limits, authentication needs, or whether it's a read-only operation. The description is minimal beyond stating the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It front-loads the core purpose and includes essential usage notes without redundancy, making it appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 3 parameters with full schema coverage, the description is adequate but has clear gaps. It covers the basic purpose and output format but lacks details on behavioral context, error handling, or integration with sibling tools beyond a brief mention. For a read operation with pagination, more guidance on usage would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the three parameters (page, per_page, parent). The description adds no parameter-specific information beyond what's in the schema, such as details on how 'parent' interacts with taxonomy hierarchy. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('taxonomy terms for listing_cat'), with specific examples of categories. It distinguishes this from sibling tools by mentioning the term `id` is used in `blz_search`, but doesn't explicitly differentiate from other listing tools like `wolnelektury_list_taxonomy`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating the term `id` should be used in `blz_search`, providing some context. However, it doesn't explicitly say when to use this tool versus alternatives like `blz_search` or other taxonomy tools, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the repository size and output format, but lacks critical behavioral details: whether this is a read-only operation, any rate limits, authentication requirements, pagination behavior beyond the 'start' parameter, or error handling. The description doesn't contradict annotations (none exist), but provides minimal behavioral context for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: first establishes the search scope and repository context, second specifies output format. Every element (repository name, dataset count, DOI prefix, return format) serves a clear purpose with zero redundant information. It's appropriately sized for a search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description provides basic context about the repository scope and output format, but lacks sufficient detail for a search tool. It doesn't explain the search algorithm's behavior, result ordering, error cases, or what 'relevance scores' mean. The description is complete enough to understand what the tool accesses, but not how it behaves during execution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 4 parameters. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., how the 'query' parameter interacts with the repository's search algorithm, what 'type' restriction means in practice). With complete schema coverage, the baseline score of 3 is appropriate as the description doesn't enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verb ('Search') and resource ('open research datasets in RePOD'), including the repository's full name and affiliation. It distinguishes from siblings by specifying the unique content scope (~3,737 datasets with DOIs under 10.18150/ prefix) and output format (JSON with relevance scores, authors, descriptions, publication dates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. While the description mentions the repository scope, it doesn't clarify when to choose repod_search over sibling tools like repod_get_dataset or other search tools (e.g., icm_search, rcin_search) that might access different datasets. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool returns 'raw JSON array of listing objects' and mentions WordPress REST API limitations for ordering. However, it doesn't cover important behavioral aspects like rate limits, authentication requirements, error conditions, or pagination details beyond the parameters. The description adds some context but leaves gaps for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with three sentences that each serve a purpose: stating the tool's purpose, explaining parameter usage, and describing the return format. It's front-loaded with the core functionality and avoids unnecessary repetition. The structure is logical and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 6 parameters, 100% schema coverage, but no annotations or output schema, the description provides adequate context about what the tool does and what it returns. However, it lacks details about the structure of returned objects, error handling, and operational constraints that would be helpful for an agent. The description is complete enough for basic usage but has room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 6 parameters thoroughly. The description adds minimal value beyond the schema - it mentions the optional nature of search/category parameters and references blz_listing_categories for term IDs, but doesn't provide additional semantic context. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches 'legal digital culture sources in Baza Legalnych Źródeł' and specifies it uses WordPress REST for listings CPT. It distinguishes from siblings like blz_get_listing (which retrieves single items) and blz_listing_categories (which provides category IDs), but doesn't explicitly contrast with other search tools on the server. The verb 'search' is specific and the resource 'legal digital culture sources' 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage guidance by mentioning 'optional full-text search and/or listing_cat term ID' and referencing blz_listing_categories for IDs. However, it doesn't explicitly state when to use this tool versus alternatives like blz_get_listing or other search tools on the server. The guidance is helpful but not comprehensive about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns HTML (not JSON), which is a key behavioral trait not evident from the schema. However, it lacks details on potential side effects (e.g., if it's read-only, which is implied but not stated), error handling, or performance considerations like rate limits, leaving gaps for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, stating the core functionality in the first clause and adding important behavioral details (HTML output) in a second sentence. There's no wasted text, though it could be slightly more structured by explicitly separating purpose from constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no annotations, no output schema), the description is partially complete. It covers the purpose and output format (HTML), but lacks details on error cases, what the HTML contains, or how it integrates with sibling tools. Without annotations or output schema, more context would help the agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with both parameters ('kind' and 'lang') well-documented in the schema itself (including enums and descriptions). The description adds no additional parameter semantics beyond what the schema provides, such as explaining the relationship between 'kind' values and the listed categories. This meets the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Browse by production kind' with specific categories (fiction, documentary, animation/experimental, magazine) and mentions it returns HTML. It distinguishes itself from sibling tools like 'fn_repo_search' by focusing on browsing by kind rather than general search, though it doesn't explicitly contrast with 'fn_repo_film_index' or 'fn_repo_get_node'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating 'same entries as the top menu,' suggesting this tool is for structured browsing akin to a website's navigation. However, it doesn't provide explicit guidance on when to use this versus alternatives like 'fn_repo_search' or 'fn_repo_film_index,' leaving the agent to infer based on the browsing vs. searching distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It usefully describes the result format ('HAL+JSON with Dublin Core metadata'), filter operator syntax, and supported operators. However, it doesn't mention important behavioral aspects like rate limits, authentication requirements, error conditions, or pagination behavior beyond the parameters. The description adds value but leaves significant gaps for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise at three sentences, with the first sentence establishing core functionality, the second detailing capabilities, and the third explaining operator syntax. It's front-loaded with the main purpose. While efficient, it could be slightly more structured by separating filter details from operator syntax.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (12 parameters, no output schema, no annotations), the description is partially complete. It covers the search scope, result format, and operator system well, but lacks information about error handling, performance characteristics, authentication, and how results are structured beyond metadata format. For a search tool without output schema, more detail about response structure would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 thoroughly. The description adds some context about filter operators and their defaults, but doesn't provide additional semantic meaning beyond what's in the parameter descriptions. It mentions 'full-text search with filters' which aligns with the schema but doesn't enhance understanding of individual parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search research data and publications in the ICM Open Research Data Repository... via DSpace 7 discovery.' It specifies the verb ('Search'), resource ('research data and publications'), and target system, distinguishing it from siblings like 'icm_get_item' which retrieves individual items rather than performing searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions the tool's capabilities but doesn't indicate when it's appropriate compared to other search tools in the sibling list (e.g., 'icm_get_item' for retrieving specific items, or other repository-specific search tools). There's no mention of prerequisites, limitations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool requires two requests (session + POST) and doesn't use KV cache, and returns raw HTML. However, it lacks details on authentication needs, rate limits, error handling, or what the HTML structure contains, which are important for a tool with 18 parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with key information in two sentences: it states the purpose and portal, notes the output format and request requirements, and provides a usage tip. There's minimal waste, though it could be slightly more structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (18 parameters, no annotations, no output schema), the description is adequate but has gaps. It covers the basic purpose and some behavioral traits but lacks details on output interpretation, error cases, or integration with sibling tools beyond 'wiedza_get_standard', making it minimally viable but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 18 parameters thoroughly with descriptions and enums. The description adds no additional parameter semantics beyond implying search functionality, meeting the baseline of 3 where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for standards on the WIEDZA portal (wiedza.pkn.pl) and returns raw HTML with a results list. It specifies the verb 'search' and resource 'norms/standards', but doesn't explicitly differentiate from sibling tools like 'pkn_search' or 'wiedza_get_standard' beyond mentioning the latter for follow-up use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning it requires two requests (session + POST) and doesn't use KV cache, and suggests using 'wiedza_get_standard' with exact standard numbers from results. However, it doesn't explicitly state when to use this tool versus alternatives like 'pkn_search' or other search tools in the sibling list, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the data source (nac.gov.pl) and output format (WordPress REST JSON), which is useful. However, it lacks details on error handling, authentication needs, rate limits, or whether it's a read-only operation (though 'Fetch' implies reading).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the key information: action, resource, source, and output format. There is no wasted verbiage, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one well-documented parameter and no output schema, the description is adequate but minimal. It covers the basics but could benefit from more behavioral context (e.g., error cases, response structure) since annotations are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with 'post_id' well-documented as a numeric ID from specific sources. The description adds context by mentioning the WordPress endpoint ('/wp/v2/posts/{id}'), which clarifies the parameter's role in the API call, providing value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and resource ('a single blog post from nac.gov.pl'), specifying it returns WordPress REST JSON from a specific endpoint. It doesn't explicitly differentiate from sibling tools like 'nac_get_page' or 'nac_site_search', but the focus on a single post by ID provides implicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning the source (nac.gov.pl) and endpoint format, and the parameter description suggests 'post_id' comes from 'nac_site_search or URLs'. However, it doesn't explicitly state when to use this tool versus alternatives like 'nac_get_page' or 'nac_site_search', leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool fetches records in XML format, mentions session dependency for 'find' results, and describes common input formats. However, it doesn't cover important behavioral aspects like error handling, response structure, pagination, or authentication requirements for a tool that presumably reads data from a server.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences. The first sentence establishes purpose and context, while the second provides usage guidance and format details. There's minimal redundancy, though the format information could be slightly more concise. Every sentence earns its place by adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description provides adequate but incomplete context. It covers the basic purpose, prerequisites, and parameter usage, but lacks information about return values, error conditions, or system-specific behaviors. Given the technical nature of Aleph X-Server operations and the absence of structured metadata, more behavioral transparency would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 three parameters thoroughly. The description adds minimal value beyond the schema: it mentions that '8-digit zero-padded entry numbers are common' for set_entry and that format defaults to 'marc', but these details are already implied or explicit in the schema. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Fetch catalogue records from the SUM Aleph X-Server `op=present` (XML, typically MARC in `<oai_marc>`)'. It specifies the verb ('fetch'), resource ('catalogue records'), and source system. However, it doesn't explicitly differentiate from sibling tools like 'sum_aleph_find' beyond mentioning prior results from 'find'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: 'Use `set_no` and `set_entry` from a prior `find` result set in the same session when search works; or indices as returned by the OPAC'. This gives specific prerequisites and alternative input sources. It doesn't explicitly state when NOT to use it or name alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return format ('full JSON including textContent, judges, courtCases, legalBases, referencedRegulations'), which is helpful, but lacks critical details like whether this is a read-only operation, error handling, rate limits, authentication needs, or performance characteristics. For a tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in a single sentence that front-loads the purpose and includes essential details about the parameter source and return format. Every part of the sentence adds value without redundancy, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is adequate but not fully complete. It covers the purpose, parameter context, and return structure, but lacks behavioral details like error cases or operational constraints. For a read operation, this is minimally viable but could be more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the parameter 'judgment_id' well-documented in the schema as a positive integer. The description adds minimal value beyond the schema by mentioning the ID sources ('from search results items[].id or /api/search/judgments'), but doesn't provide additional syntax or format details. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch one SAOS judgment') and resource ('by numeric id'), distinguishing it from sibling tools like 'saos_search_judgments' which returns multiple results. It precisely defines what the tool does without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool ('by numeric id from search results items[].id or /api/search/judgments'), indicating it's for retrieving a single judgment after obtaining an ID. However, it doesn't explicitly state when not to use it or name alternatives like 'saos_search_judgments' for initial searches, though this is somewhat implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the search functionality, result format ('HAL+JSON with full Dublin Core metadata, compacted into a readable summary'), and pagination approach ('0-based pagination'), but doesn't mention rate limits, authentication requirements, or error handling. It provides moderate behavioral context but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose. All sentences contribute useful information about scope, functionality, and syntax. It could be slightly more structured but avoids unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 11 parameters, 100% schema coverage, but no output schema and no annotations, the description provides adequate context about what the tool does and how to use parameters. However, it lacks details about the output structure beyond 'readable summary' and doesn't address potential limitations or error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, so the baseline is 3. The description adds some value by explaining the filter operator syntax ('Each filter value may include an explicit operator suffix separated by a comma') and listing supported operators, but doesn't provide additional semantic context beyond what's already in the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search publications'), target resource ('AGH University of Krakow Repository'), and scope ('theses, dissertations, articles, technical reports, and monographs from AGH'). It distinguishes from sibling tools like 'agh_get_item' by focusing on search rather than retrieval of individual items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Search publications in the AGH University of Krakow Repository'), but doesn't explicitly mention when not to use it or compare it to alternatives like 'agh_get_item' for individual item retrieval. The context is sufficient but lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behavioral traits: it's a fetch/read operation (implied by 'Fetch'), mentions pagination behavior ('Pagination is 0-based'), and reveals it's an API call ('API: GET /data/by-variable/{var-id}'). However, it doesn't cover rate limits, authentication needs, error conditions, or response format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose. All sentences earn their place by adding context about parameter usage and API details. However, the final API reference could be more integrated with the preceding content rather than appended as a separate note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no annotations, and no output schema, the description provides adequate but incomplete context. It covers the core purpose and some behavioral aspects but lacks details about response format, error handling, and comprehensive usage scenarios. The 100% schema coverage helps, but more behavioral context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 thoroughly. The description adds minimal value beyond the schema - it mentions unit_level and unit_parent_id for scoping, year filtering, and pagination being 0-based, but these are already covered in parameter descriptions. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch statistical values'), target resource ('for one variable across territorial units'), and scope ('e.g. all voivodeships'), distinguishing it from sibling tools like bdl_get_variable or bdl_search_variables which likely handle metadata rather than actual data values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Set unit_level... and optionally unit_parent_id to scope results; year filters which periods are returned'), but doesn't explicitly mention when to use alternatives like bdl_get_data_by_unit or other search tools. The guidance is practical but lacks sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns HTML lists with links to specific URLs, which is useful behavioral context. However, it doesn't mention potential limitations like pagination, error handling, or performance characteristics. The description adds value beyond the schema but doesn't fully cover all behavioral traits a user might need.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences that are front-loaded with the core purpose. Every sentence earns its place: the first explains what the tool does and its parameters, the second clarifies the output format and real-world equivalent. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is reasonably complete. It covers the purpose, parameter context, and output format. However, without an output schema, it could benefit from more detail about the HTML structure or error cases. The mention of the equivalent site helps, but some behavioral aspects remain unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description doesn't add any additional parameter semantics beyond what's in the schema (e.g., it doesn't explain the significance of 'INNE' or language choice). Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Browse the film catalog by first letter of title') and resource ('film catalog'), and distinguishes it from siblings by mentioning it returns HTML links similar to the site 'katalog filmów'. It explicitly mentions the letter range (A-Z, Polish letters, or INNE), which differentiates it from general search tools like fn_repo_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating it's for browsing by first letter and returns HTML lists, but it doesn't explicitly say when to use this tool versus alternatives like fn_repo_search or fn_repo_browse_kind. It mentions the site 'katalog filmów' as a reference, which provides some contextual guidance but lacks explicit when/when-not instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the search supports full-text with filters, sort options, 0-based pagination, HAL+JSON results with highlights and metadata, and detailed operator syntax for filters. However, it doesn't mention rate limits, authentication requirements, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose and key features. It uses two sentences efficiently to convey search capabilities, result format, and operator details without unnecessary repetition. Minor improvements could include bullet points for readability, but overall it's well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (19 parameters, no output schema, no annotations), the description is moderately complete. It covers the search functionality, result format, and operator syntax, but lacks details on output structure (beyond HAL+JSON), error cases, or performance considerations. With no output schema, more information on return values would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so parameters are well-documented in the schema itself. The description adds value by explaining the operator syntax for filter values (e.g., 'Smith,equals') and listing supported operators, which complements the schema. However, it doesn't provide additional semantic context beyond what the schema already covers for most parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches publications in the Jagiellonian University Repository via DSpace 7 discovery, specifying the resource (publications in RUJ) and action (search). It distinguishes itself from sibling tools like 'ruj_get_item' by focusing on search functionality rather than retrieval of individual items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching publications with full-text and filtering capabilities, but does not explicitly state when to use this tool versus alternatives like 'ruj_get_item' or other repository search tools in the sibling list. It provides context about search features but lacks explicit guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the operation as a 'fetch' (implying read-only) and specifies the API method (GET), which suggests safe retrieval. However, it lacks details on error handling, rate limits, authentication needs, or response format, leaving gaps in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded, consisting of a single sentence that directly states the purpose and usage context. Every word earns its place, with no wasted information or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (fetch operation with 2 parameters), no annotations, and no output schema, the description is minimally adequate. It covers the core purpose and usage context but lacks details on behavioral aspects (e.g., response structure, errors) that would enhance completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema fully documents both parameters. The description adds no additional parameter semantics beyond what the schema provides (e.g., it doesn't explain the significance of 'variable_id' or 'lang' choices). Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch metadata') and resource ('one BDL variable by numeric id'), and distinguishes it from sibling tools by specifying the source of the ID ('from bdl_search_variables results'). It also mentions the API endpoint, providing technical context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: after obtaining a variable ID from 'bdl_search_variables'. However, it does not explicitly state when not to use it or name alternatives (e.g., 'bdl_search_variables' for searching, 'bdl_get_data_by_variable' for data retrieval), which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about the default format (jats) and what it includes (abstract, keywords, etc.), but does not mention potential limitations like rate limits, authentication needs, or error handling. It adequately describes the core behavior but lacks operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste: the first states the purpose and key input, the second explains the default behavior and its advantages. It is front-loaded with essential information and efficiently structured, earning its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description provides a clear purpose and some behavioral context but lacks details on return values, error cases, or operational constraints. It is adequate for a simple fetch tool but could be more complete to fully guide an agent without structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds marginal value by explaining the default format (jats) and its benefits ('includes abstract, keywords, affiliations, and references'), but does not provide additional syntax or usage details beyond what the schema specifies. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch'), resource ('full metadata record for a single article from Biblioteka Nauki'), and key identifier ('by its numeric ID'), distinguishing it from sibling tools like 'bn_search_articles' which searches rather than fetches a specific item. It provides a complete purpose statement without being tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying it's for fetching a single article by ID, suggesting it should be used when you have a specific article ID from search results. However, it does not explicitly state when not to use it or name alternatives like 'bn_search_articles' for finding articles without an ID, which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return format ('Returns HTML') and hints at content ('metadata, description, video embeds, person links'), which adds context. However, it lacks details on error handling, performance, or authentication needs, leaving gaps in behavioral understanding for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first clause and efficiently uses two sentences to cover action, parameters, and output. Every sentence adds value without redundancy, making it appropriately concise and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations and no output schema, the description provides basic context on purpose and return format but lacks details on error cases, rate limits, or full behavioral traits. For a simple read operation with two parameters, it is adequate but incomplete, as it doesn't fully compensate for the missing structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value by referencing the node ID in context ('as in /?q=pl/node/8937'), which provides a usage example, but does not elaborate beyond what the schema provides. Given the high coverage, a baseline of 3 is appropriate, but the example slightly enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch one repository page'), identifies the resource ('by Drupal node id'), and distinguishes it from sibling tools like 'fn_repo_search' and 'fn_repo_browse_kind' by specifying it retrieves a single page rather than searching or browsing. It also mentions the return format ('Returns HTML'), which helps differentiate its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying it fetches a single page by node ID, suggesting it should be used when you have a specific numeric ID from search results. However, it does not explicitly state when to use this tool versus alternatives like 'fn_repo_search' or provide exclusions or prerequisites, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: pagination (0-based), filtering options, that omitting name filters enables browsing, and that results include profileIds and URLs. However, it lacks details on rate limits, authentication needs, error handling, or the exact structure of the response (beyond mentioning 'large totalHits'), leaving some gaps for a mutation-free but complex search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first covers purpose and key features (search, pagination, filters), and the second explains result usage and sibling tool linkage. Every word adds value, with no redundancy or fluff, making it easy to parse and front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, search functionality) and lack of annotations or output schema, the description is adequate but incomplete. It covers the basic operation, filtering logic, and result usage, but misses details like response format (beyond mentioning profileId and URLs), error cases, or performance considerations (e.g., handling of 'large totalHits'). For a search tool with no structured output, more behavioral context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds minimal value beyond the schema: it mentions filtering by surname/first name/domain code and that omitting name filters enables browsing, but these are already implied or stated in the schema descriptions. No additional syntax, format, or usage nuances are provided, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search scientist profiles'), target resource ('Ludzie Nauki (ludzie.nauka.gov.pl), Poland's public researcher registry'), and distinguishes it from siblings like 'ludzie_get_scientist' (which retrieves individual profiles) and 'ludzie_semantic_search' (which presumably uses different search logic). It's precise about what the tool does without being tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for structured searches with pagination and filtering. It explicitly mentions using 'ludzie_get_scientist' with the profileId from results, distinguishing it from that sibling. However, it doesn't explicitly state when NOT to use it (e.g., vs. 'ludzie_semantic_search') or detail prerequisites, keeping it from a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It describes the protocol (OAI-PMH GetRecord) and acceptable ID formats, which adds useful context. However, it doesn't disclose important behavioral traits like error handling, response format, authentication requirements, or rate limits that would be helpful for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise - a single sentence that efficiently communicates the tool's purpose, protocol, and parameter usage. Every word earns its place with zero wasted information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with good schema coverage but no output schema, the description provides adequate basic context. However, it lacks information about return values, error conditions, or any special behavioral considerations that would help an agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents both parameters thoroughly. The description adds some value by explaining the two acceptable formats for record_id (numeric id or full OAI id), but doesn't provide additional semantic context beyond what's in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch a single RCIN object via OAI-PMH GetRecord'), identifies the resource ('RCIN object'), and distinguishes it from sibling tools like 'rcin_search' by specifying it retrieves a single record rather than performing searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool (to fetch a single record by ID) and implicitly contrasts with search tools in the sibling list. However, it doesn't explicitly state when NOT to use it or name specific alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It describes the action (metadata retrieval) and format options, but doesn't disclose behavioral traits like rate limits, authentication needs, error handling, or what the output looks like (though no output schema exists). It's adequate but lacks depth on operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys purpose and key usage details without any wasted words. It's front-loaded with the core action and resource, making it highly concise and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only metadata retrieval tool with 2 parameters (100% schema coverage) but no annotations or output schema, the description is minimally complete. It covers the what and how, but lacks details on output format, error cases, or integration context that would help an agent use it more effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters thoroughly. The description adds minimal value beyond the schema by mentioning the format options, but doesn't provide additional semantic context like DOI formatting examples or use cases for each format. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get metadata') and resource ('for a specific dataset in RePOD by its DOI'), distinguishing it from the sibling 'repod_search' tool which presumably searches rather than retrieves a specific dataset. It's precise 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool (to get metadata for a specific dataset by DOI) and offers guidance on format choices, but it doesn't explicitly state when NOT to use it or mention alternatives like 'repod_search' for broader queries. The format guidance is helpful but not a full alternative analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It effectively communicates that this is a read-only operation ('Retrieve') and specifies the input source, but lacks details on error handling, rate limits, authentication needs, or response format. It adds some behavioral context but is incomplete for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the tool's purpose, usage context, and parameter source without any redundant information. It is front-loaded with the core action and appropriately sized for its complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is adequate but minimal. It covers the basic purpose and usage context but lacks details on behavioral traits like error responses or metadata structure, which could be helpful despite the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the 'uuid' parameter. The description adds minimal value by reiterating that the UUID comes from 'ruj_search' results, but does not provide additional semantics beyond what the schema already states. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Retrieve full metadata'), target resource ('a single item in the Jagiellonian University Repository'), and method ('by its UUID'). It explicitly distinguishes from sibling 'ruj_search' by noting the UUID source, making the purpose unambiguous and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: after obtaining a UUID from 'ruj_search' results. However, it does not explicitly state when not to use it or mention alternatives like other 'get_item' tools (e.g., 'agh_get_item'), leaving some ambiguity in sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it specifies the search system (DSpace 7 discovery), output format (HAL+JSON with Dublin Core metadata), filter operators with defaults, and special syntax for date ranges. However, it lacks details on rate limits, authentication needs, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first establishes purpose and scope, the second details behavioral aspects like operators and output format. Every sentence adds critical information without redundancy, making it front-loaded and zero-waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 10 parameters, 100% schema coverage, and no output schema, the description is quite complete. It covers system context, output format, and operator behavior. However, without annotations or output schema, it could benefit from mentioning response structure or pagination details to achieve full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing detailed parameter documentation. The description adds value by explaining operator suffixes and defaults for filters, and clarifying date range syntax, but does not significantly expand on parameter meanings beyond what the schema already covers. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search publications'), target resource ('Adam Mickiewicz University Repository'), and method ('via DSpace 7 discovery'). It distinguishes itself from sibling tools like 'amu_get_item' by focusing on search functionality rather than retrieval of individual items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through mention of 'full-text search with filters' and 'HAL+JSON with Dublin Core metadata,' but does not explicitly state when to use this tool versus alternatives like 'amu_get_item' or other search tools in the sibling list. No explicit when-not-to-use guidance or prerequisite information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: the data source (Polish government portal), dataset count (43,000+), academic flag (has_research_data=true), and return format (JSON with specific fields like title, category, license, institution, download stats). However, it lacks details on rate limits, authentication needs, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with essential information in two efficient sentences. The first sentence covers purpose and scope, while the second details return format and academic data flag. There is no wasted text, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (search with 5 parameters, no output schema, and no annotations), the description is mostly complete. It covers the data source, scope, academic flag, and return format. However, it lacks details on pagination behavior (implied by parameters but not explained), error cases, or example usage, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters thoroughly. The description does not add any parameter-specific semantics beyond what the schema provides (e.g., it doesn't explain query syntax or category mappings). The baseline score of 3 is appropriate as the schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search'), the target resource ('Polish government open data portal (dane.gov.pl)'), and distinguishes it from siblings by specifying the portal's scope (43,000+ datasets from ministries, municipalities, and public institutions). It also mentions the academic dataset flag, which further differentiates it from generic search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning the portal's scope and academic datasets, but it does not explicitly state when to use this tool versus alternatives like 'dane_get_dataset' or other search tools in the sibling list. No exclusions or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses important behavioral aspects: returns specific data fields (title, catalog line, image URL, plain text), respects copyright/terms, and warns against bulk-downloading. However, it doesn't mention error conditions, rate limits, authentication needs, or response format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. First sentence covers purpose, parameters, and return values. Second sentence adds important behavioral context (copyright). Every word earns its place and information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with no output schema, the description is reasonably complete. It covers what the tool does, what it returns, parameter context, and important usage constraints. The main gap is lack of output format details, but given the tool's simplicity, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single 'slug' parameter. The description adds minimal value beyond the schema by mentioning the slug comes 'from fototekaslaska_search' and the URL pattern, but doesn't provide additional syntax or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch'), resource ('one Fototeka Śląska photo page'), and mechanism ('by URL slug'), distinguishing it from sibling tools like fototekaslaska_search. It specifies the exact URL pattern (/galeria/{slug}/) and what data is returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning the slug comes 'from fototekaslaska_search' and provides copyright warnings. However, it doesn't explicitly state when to use this tool versus alternatives like fototeka_get_photo or other get_item tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively indicates this is a read-only operation ('Get full JSON metadata') and specifies the scope of returned data. However, it lacks details on error handling, rate limits, authentication needs, or response format beyond 'JSON metadata,' leaving some behavioral aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by clarifying details. Every sentence earns its place by specifying inclusions, exclusions, and data sources without redundancy. It is appropriately sized and efficiently structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage context, and data scope well. However, without an output schema, it could benefit from more detail on the structure of the returned JSON metadata to fully guide the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds minimal value beyond the schema by mentioning 'numeric id (from ninateka_search items[].id)' for 'vod_id', but does not provide additional syntax, format, or usage details. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get full JSON metadata'), target resource ('one Ninateka item'), and key identifier ('by numeric id'). It explicitly distinguishes this tool from potential siblings by specifying what it includes ('description, categories, images, type') and excludes ('Does not return streaming URLs or DRM — metadata only'), making its purpose distinct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: after obtaining an ID from 'ninateka_search items[].id' and when only metadata is needed. However, it does not explicitly mention when not to use it (e.g., for streaming URLs) or name specific alternative tools, though the exclusion of streaming/DRM implies alternatives exist for those purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the return format ('compact metadata (title, inventory, tags, preview path)'), which is helpful. However, it doesn't mention error handling, rate limits, authentication needs, or whether the operation is idempotent, leaving behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by return details and usage guidance in just two sentences. Every word earns its place with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, 100% schema coverage, no output schema), the description is mostly complete. It covers purpose, parameter usage, and return format. However, without annotations or output schema, it could benefit from more behavioral details like error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 the single parameter 'artwork_id' with examples. The description adds minimal value by restating the parameter usage but doesn't provide additional semantics beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Fetch'), resource ('one artwork record from PAUart'), and key identifier ('by its catalogue id'). It distinguishes from sibling 'pauart_search' by specifying this retrieves a single record rather than searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context by stating 'Use ids returned by pauart_search,' which implicitly guides when to use this tool versus its sibling. However, it doesn't explicitly state when NOT to use it or mention alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it uses a POST API endpoint, returns specific data fields (titles, inventory numbers, tags, object types), explains the 'artworks_only' filtering logic, and mentions the HTTP protocol. However, it doesn't cover error handling, rate limits, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three sentences: purpose statement, return values, parameter behavior explanation, and API/UI context. Each sentence adds value, though the final sentence about the UI could be more tightly integrated with the usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no annotations and no output schema, the description provides adequate coverage of purpose and basic behavior. However, it lacks information about response format, error conditions, and performance characteristics that would be helpful for an AI agent. The 100% schema coverage helps, but output details remain unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it only explains the 'artworks_only' parameter's effect on filtering. This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search the PAU (Polish Academy of Arts and Sciences) art collection catalogue (PAUart, pauart.pl).' It specifies the exact resource (PAUart collection catalogue) and distinguishes it from the sibling 'pauart_get_artwork' tool by focusing on search rather than retrieval of individual items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool: for searching the PAUart catalogue via its public API. It mentions the UI alternative ('The UI is at http://www.pauart.pl/app') but doesn't explicitly contrast with sibling tools or specify when not to use it. This gives good operational context but lacks sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format ('Returns JSON with total_count and a list of items including DOI, description, authors, and citation'), which is valuable. However, it doesn't mention pagination behavior (implied by parameters but not explained), rate limits, authentication requirements, or error handling, leaving gaps for a mutation-free search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences: the first establishes purpose and context, the second provides key usage guidance and output format. Every word earns its place, and the most important information (what it does and how to use it) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no annotations, 100% schema coverage, but no output schema, the description does well by explaining the return format. It covers the essential context (what it searches, what it returns, a key usage tip). The main gap is lack of explicit sibling differentiation, but given the schema handles parameters well, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all 4 parameters. The description adds marginal value by reinforcing the query parameter's special value ('Use query='*' to browse all available datasets'), but doesn't provide additional semantic context beyond what's in the schema descriptions. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Search') and resource ('research datasets in RODBuK'), specifies the repository's scope ('Krakow inter-university open research data repository'), and distinguishes it from siblings by mentioning it's powered by Harvard Dataverse, which no other sibling tool references. This provides specific differentiation beyond just the search functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Search research datasets in RODBuK') and includes a specific usage tip ('Use query='*' to browse all available datasets'). However, it doesn't explicitly state when not to use it or name alternatives among the many sibling search tools, which would be needed for a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the return format ('Returns JSON with items[].id, href, textContent snippets, court metadata') which is helpful, but doesn't cover important aspects like pagination behavior (implied by page parameters but not explained), rate limits, authentication requirements, or error conditions. The description adds value but leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose. It efficiently covers search scope, key parameters, return format, and sibling tool relationship in three sentences. While dense, every sentence adds value and there's no wasted text. The structure moves logically from purpose to usage to output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (28 parameters, no output schema, no annotations), the description provides adequate but incomplete coverage. It explains the purpose, basic usage, and return structure, but doesn't address pagination behavior, error handling, or the relationship between the many filtering parameters. For such a complex search tool with rich filtering options, more contextual guidance would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds some context by mentioning the SAOS query language link and listing filterable fields, but doesn't provide significant additional parameter semantics beyond what's already documented in the comprehensive schema. It gives a high-level overview but the schema does the heavy lifting for parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb ('Search') and resource ('Polish court judgments in SAOS'), and distinguishes from sibling tools by mentioning 'saos_get_judgment' for full text retrieval. It provides concrete scope details about what can be searched (full-text/metadata phrase, dates, case numbers, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when-to-use guidance: 'Use `all` for full-text / metadata phrase' and 'For full text use saos_get_judgment with id.' It clearly distinguishes this search tool from the retrieval tool for full content, giving the agent clear alternatives based on the user's need.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it specifies the search system (DSpace 7 discovery), result format (HAL+JSON with Dublin Core metadata), operator syntax with defaults, and supported operators. It misses details like pagination behavior or error handling, but covers essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first establishes purpose and scope, the second details operational specifics. Every phrase adds necessary information without redundancy, making it front-loaded and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 13 parameters, 100% schema coverage, and no output schema, the description is largely complete. It covers the search system, filters, operators, and result format. However, it lacks information on response structure (e.g., pagination metadata) which would be helpful given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 13 parameters thoroughly. The description adds value by explaining operator suffixes and defaults for filters, but does not provide additional semantic context beyond what the schema descriptions offer. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search publications'), the target resource ('University of Applied Sciences in Nowy Sącz Repository'), and the method ('via DSpace 7 discovery'). It distinguishes from sibling tools like 'uafm_get_item' by focusing on search rather than retrieval of individual items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching publications with various filters, but does not explicitly state when to use this tool versus alternatives like 'uafm_get_item' or other search tools in the sibling list. It provides context about supported filters but lacks explicit guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the return format (Dublin Core metadata with specific fields) and the UUID source, but doesn't mention error handling, rate limits, authentication needs, or whether this is a read-only operation (though implied by 'Retrieve').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. First sentence states purpose and parameter, second describes return values. Every element earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with no output schema, the description provides good coverage: purpose, parameter context, and return format. However, it lacks error scenarios or behavioral constraints that would be helpful given no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 the UUID parameter. The description adds value by explaining where to find the UUID ('uuid' field of agh_search results) and providing context about its purpose, but doesn't add syntax details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and resource 'full metadata for a single item in the AGH University of Krakow Repository', specifying it's by UUID. It distinguishes from sibling 'agh_search' by focusing on single-item retrieval rather than search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use when you have a UUID from 'agh_search results'. However, it doesn't explicitly state when NOT to use this tool or name alternatives beyond the implied 'agh_search' for finding UUIDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly indicates this is a read operation ('Retrieve'), which is helpful. However, it doesn't disclose other behavioral traits like error handling, rate limits, authentication needs, or what 'full metadata' includes. The description adds basic context but leaves significant behavioral aspects unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first sentence states the core purpose with all essential elements. The second sentence provides crucial usage guidance and sibling relationship. Every word serves a clear purpose, and information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one well-documented parameter and no output schema, the description is mostly complete. It covers purpose, usage context, and parameter source. The main gap is lack of information about return values (what 'full metadata' includes), which would be helpful given no output schema. However, for this complexity level, it's reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single 'uuid' parameter. The description adds minimal value by mentioning UUIDs come from 'amu_search results', which provides context but doesn't add semantic details beyond what the schema provides. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Retrieve full metadata'), target resource ('a single item in the Adam Mickiewicz University Repository'), and method ('by its UUID'). It explicitly distinguishes from sibling 'amu_search' by mentioning UUIDs come from that tool's results, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 ('for a single item by UUID') and when not to use it (implied: not for searching or multiple items). It names the alternative tool ('amu_search') and specifies the prerequisite relationship ('UUID is found in the 'uuid' field of amu_search results'), giving complete usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the output format (HTML) and the source of IDs, which is helpful behavioral context. However, it doesn't mention potential error conditions, authentication requirements, rate limits, or whether the operation is idempotent/safe. For a read operation with no annotations, this is adequate but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys purpose, parameter context, and output format. Every word earns its place, with no redundancy or unnecessary elaboration. It's front-loaded with the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one fully documented parameter and no output schema, the description provides sufficient context: it states what the tool does, when to use it, the output format, and parameter semantics. The main gap is the lack of behavioral details like error handling or performance characteristics, but given the tool's simplicity, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 the single parameter 'resource_id' as an integer >0 from search/browse results. The description adds value by explaining where these IDs appear ('result lists as links `/baztol_czytelnik/baztol?id=…`'), providing practical context beyond the schema's technical definition. With only one parameter, this is strong compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch'), resource type ('BazTOL resource description page'), and format ('HTML'), and distinguishes it from sibling tools by specifying it retrieves a single resource by numeric ID rather than searching or browsing. It explicitly mentions where IDs come from ('result lists as links'), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when you have a numeric resource ID from search/browse results. It implicitly distinguishes from sibling tools like 'baztol_search' or 'baztol_browse_domain' by focusing on single-resource retrieval rather than list operations. However, it doesn't explicitly state when NOT to use it or name specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it returns HTML (not JSON), uses POST like the website, has pagination (20 hits per page, 1-based), and notes there's no official JSON API. This covers format, method, and limitations, though it could mention error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with every sentence earning its place: it states the purpose, output format, pagination details, and technical method concisely in three sentences, with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 2 parameters with full schema coverage, the description is mostly complete for a search tool. It covers purpose, behavior, and parameters well, but could improve by detailing the HTML structure or error cases. It's sufficient but has minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters ('query' and 'page') fully. The description adds minimal value beyond the schema by mentioning pagination context, but does not provide additional syntax or format details. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Search') and resource ('BazTOL (Polish technical-science gateway, PUT library)'), and distinguishes it from siblings like 'baztol_browse_domain' and 'baztol_get_resource' by specifying it returns a result list from a search operation. It's specific and avoids tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (searching BazTOL) and mentions pagination details, but does not explicitly state when not to use it or name alternatives among siblings (e.g., 'baztol_browse_domain' or 'baztol_get_resource'). It implies usage through the search focus.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the output includes 'all downloadable resources' and API links, which adds useful context about return behavior. However, it lacks details on error handling, rate limits, or authentication needs, leaving gaps for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and includes essential details without waste. Every part earns its place by specifying the action, resource, and parameter context efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete. It covers purpose, usage context, and output details. However, without annotations or output schema, it could benefit from more behavioral transparency, such as error cases or response format specifics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 the dataset_id parameter. The description adds value by clarifying that the ID is 'the integer id field returned by dane_search', providing context beyond the schema's basic description. With only one parameter, this extra semantic detail is helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'full details for a specific dataset on dane.gov.pl', specifying it includes downloadable resources like CSV, XLSX, JSON, and API links. It distinguishes from its sibling 'dane_search' by focusing on individual dataset retrieval rather than searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating the dataset_id comes from 'dane_search results', indicating when to use this tool after a search. However, it does not explicitly mention when not to use it or name alternatives beyond the implied sibling relationship.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it returns plain text extracted from HTML (strips markup), truncates for LLM context, and mentions copyright/database notice obligations. It doesn't specify error handling or rate limits, but covers the essential transformation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly packed sentences with zero waste. Each sentence adds critical information: what the tool does, how it transforms the output, and legal considerations. Perfectly front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with no output schema, the description is quite complete. It explains the transformation (HTML to plain text), truncation behavior, and legal context. Could potentially mention error cases or response format, but covers the essential context well given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single parameter. The description adds marginal value by mentioning the parameter comes 'from filmpolski_search links index.php/{id}', but doesn't provide additional semantic context beyond what's in the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('fetch one FilmPolski.pl record'), resource ('by numeric id'), and distinguishes it from siblings by specifying it's for single-item retrieval versus the filmpolski_search tool for searching. It explicitly mentions the source URL pattern and output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('by numeric id from filmpolski_search links'), implying it should be used after obtaining IDs from the search sibling. However, it doesn't explicitly state when NOT to use it or name alternative tools beyond the implied filmpolski_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool scrapes HTML (no official JSON API), returns compact JSON with IDs for follow-up queries, and requires respecting site terms (short excerpts, citation). However, it lacks details on rate limits, error handling, or response structure, which would be helpful for a scraping tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by implementation details and usage notes. Every sentence adds value: HTML parsing, match_mode specifics, and site terms. It is compact with zero wasted words, efficiently covering essential information in three concise statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description does well to cover the scraping nature, match modes, and legal terms. However, for a tool that parses HTML into JSON, more details on the output structure (e.g., fields returned, pagination) would enhance completeness. It adequately informs usage but leaves some behavioral aspects implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters thoroughly. The description adds minimal value beyond the schema: it reiterates match_mode options and provides an example for exact mode ('Surname, Firstname'), but does not explain parameter interactions or search semantics in depth. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool searches FilmPolski.pl (Polish Film Database) for films, TV, theatre, and people/institutions. It specifies the verb 'search' and resource 'FilmPolski.pl', distinguishing it from sibling 'filmpolski_get_item' which retrieves individual items. The mention of HTML parsing into JSON further clarifies the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for searching the Polish Film Database. It implicitly distinguishes from 'filmpolski_get_item' by noting that results include 'ids for filmpolski_get_item', but does not explicitly state when to choose one over the other or mention other search alternatives among siblings. The match_mode details offer usage guidance within the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it returns HTML result pages (not JSON API), explains the format of facet filters, and clarifies the 0-based paging. However, it does not mention rate limits, authentication needs, or error handling, leaving some behavioral aspects uncovered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by concise details on output format and parameter usage. Every sentence adds value without redundancy, making it efficiently structured and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, output format, and parameter nuances, but lacks details on error cases or performance limits, which could enhance completeness for a search tool with no structured output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters thoroughly. The description adds some context for facets (e.g., examples like bundle:doc) and page (0-based index), but does not provide significant additional meaning beyond what the schema offers. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches the Filmoteka Narodowa digital repository via Apache Solr, specifying both the target resource (the repository) and the method (Solr search). It distinguishes from siblings like fn_repo_browse_kind and fn_repo_film_index by focusing on search functionality, making the purpose specific and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (searching the repository) and mentions optional facets and page parameters, but does not explicitly state when not to use it or name specific alternatives among the many sibling tools. The guidance is helpful but lacks explicit exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states what the tool returns (raw HTML with metadata) and what it doesn't return (full-resolution image file), which is valuable context. However, it doesn't mention potential error conditions, rate limits, authentication requirements, or response format details beyond 'raw HTML'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences with zero waste. The first sentence states the core functionality, the second provides important clarifications about what is and isn't returned. Every word serves a purpose and the information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with no output schema, the description is reasonably complete. It explains what the tool does, what it returns, and distinguishes it from search operations. However, without annotations or output schema, it could benefit from more detail about error handling or response structure, though the core functionality is well-covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the single parameter well-documented in the schema. The description adds minimal value beyond the schema by mentioning where IDs come from ('search results and collection links on fototeka.fn.org.pl'), but doesn't provide additional semantic context about parameter usage or constraints beyond what's already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verb ('Fetch') and resource ('Fototeka HTML page for a single photo'), and distinguishes it from sibling tools by specifying it retrieves a single photo by ID rather than performing searches or getting different types of items. It explicitly mentions what it returns ('raw HTML with metadata, description, related links') and what it doesn't return ('not the full-resolution image file').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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: 'by numeric id' from specific sources ('search results and collection links on fototeka.fn.org.pl'). It also distinguishes from alternatives by specifying this is for single photo retrieval rather than search operations, with a clear sibling tool 'fototeka_search' available for search functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by specifying the return format ('raw HTML'), what's included ('metadata, credits, image links'), and clarifying there's 'no separate JSON API.' However, it doesn't mention potential error cases, rate limits, authentication needs, or whether this is a read-only operation (though 'fetch' implies reading). The description adds useful context but lacks comprehensive behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences with zero waste. The first sentence states the core functionality and parameter source, while the second provides implementation details (URL pattern) and output characteristics. Every word contributes to understanding the tool's operation and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with no output schema, the description provides good completeness. It covers the purpose, parameter semantics, return format, and implementation details. However, without annotations or output schema, it could benefit from more behavioral context like error handling or response structure. The description compensates well for the lack of structured metadata but doesn't fully bridge all gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already fully documents the single parameter. The description adds valuable semantic context by explaining where the poster_id comes from ('from gapla_search links plakat/ID/…') and how it relates to the URL pattern. This provides practical guidance beyond the schema's technical validation rules, though it doesn't add syntax or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('fetch', 'returns') and resources ('Gapla poster detail page as HTML', 'raw HTML'). It distinguishes from sibling tools by specifying it retrieves individual poster details by ID, unlike gapla_search which presumably searches for posters. The description explicitly mentions the URL pattern and what the tool returns, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to fetch a single poster detail page by numeric ID, specifically IDs obtained from gapla_search links. It mentions the URL pattern and that the slug is optional, giving practical usage hints. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the many sibling tools, though the connection to gapla_search is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It clearly describes the read-only nature ('Retrieve') and specifies the data source (ICM Open Research Data Repository). However, it doesn't disclose behavioral traits like rate limits, authentication requirements, error conditions, or response format details, leaving gaps for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two tightly focused sentences. The first sentence establishes purpose and scope, while the second provides crucial usage guidance. Every word earns its place with zero redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with no output schema, the description provides strong purpose clarity and usage guidelines. However, without annotations or output schema, it lacks details about response format, error handling, and behavioral constraints. The description is complete enough for basic use but leaves operational questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing complete documentation of the single 'uuid' parameter. The description adds marginal value by reinforcing the UUID comes from 'icm_search results' and specifying the repository context, but doesn't provide additional semantic details beyond what's already in the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Retrieve full metadata') and resource ('a single item in the ICM Open Research Data Repository') with precise scope ('by its UUID'). It explicitly distinguishes from sibling 'icm_search' by noting the UUID comes from that tool's results, establishing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 ('Retrieve full metadata for a single item... by its UUID') and when not to (implied: use icm_search for finding items). It names the alternative tool ('icm_search') and specifies the prerequisite relationship ('UUID is found in the 'uuid' field of icm_search results'), giving complete usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: the data format (JSON), the scope of data (all active stations or single station), the refresh frequency (roughly every hour), and the precedence rule for parameters. It doesn't mention error handling, rate limits, or authentication requirements, but covers key operational aspects well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by details on parameters and behavior. Every sentence earns its place by providing essential information without redundancy. The structure flows logically from general to specific.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 optional parameters, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, key behaviors, and parameter semantics. However, it doesn't describe the JSON structure of the return data (e.g., fields like temperature, wind speed), which would be helpful since there's no output schema. For a data retrieval tool, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters thoroughly. The description adds some value by reiterating the precedence rule and providing examples (e.g., '12500 for Jelenia Góra', 'jeleniagora'), but doesn't add significant meaning beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('retrieve'), resource ('current synoptic weather station readings'), and source ('IMGW-PIB'). It distinguishes this tool from its sibling tools (like imgw_hydro, imgw_meteo, imgw_warnings) by specifying it returns synoptic station data with specific weather parameters, not hydrological, meteorological, or warning data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: to get weather readings for all active synoptic stations in Poland or for a single station when station_id or station_name is provided. It explains the precedence rule if both parameters are given. However, it doesn't explicitly state when NOT to use it or mention alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the return format ('JSON with title, texts (PDF file names), references') which is valuable behavioral information. However, it doesn't mention error conditions, rate limits, authentication needs, or whether this is a read-only operation (though 'fetch' implies it).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three sentences: purpose statement, parameter example with explanation, and return format. Every sentence adds value with zero wasted words. It's appropriately sized for a single-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with 1 parameter (100% schema coverage) and no output schema, the description provides good context: purpose, parameter semantics with example, and return format. It could be more complete by mentioning error cases or authentication, but covers the essential usage scenario adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 the 'eli' parameter well. The description adds meaningful context by explaining ELI structure with a concrete example ('DU/2026/370 — Dziennik Ustaw, year 2026, position 370') and connecting it to search results, which helps the agent understand the parameter's purpose beyond the schema's technical description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch one legal act'), resource ('from ISAP'), and identifier type ('by ELI identifier'). It distinguishes from sibling 'isap_search_acts' by specifying retrieval of a single item rather than searching. The example ELI format reinforces the specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an ELI identifier from search results, but doesn't explicitly state when to use this vs. alternatives like 'isap_search_acts' or other legal database tools. It provides context about the ELI format being the same as in search results, which helps with workflow understanding.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behavioral traits: it's a search operation (implied read-only), returns raw JSON with specific fields, and includes a rate limit hint ('capped at 100 here'). It also clarifies that 'keyword' matches controlled vocabulary tags, not free text. However, it doesn't mention authentication needs, error handling, or pagination details beyond offset.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by key usage notes and return format, ending with a reference link. Every sentence earns its place: the first defines the tool, the second clarifies parameter semantics, the third lists filterable fields, and the fourth specifies output and API docs. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (18 parameters, no annotations, no output schema), the description is reasonably complete. It covers purpose, key parameter nuances, return format, and API reference. However, it doesn't detail the JSON structure of 'items[]' (e.g., field descriptions) or error scenarios, which could be helpful for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 18 parameters thoroughly. The description adds minimal value beyond the schema: it clarifies that 'title' is for full-text-in-title search and 'keyword' matches ISAP tags, but doesn't explain other parameters like date ranges or sorting. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search Polish legal acts indexed in ISAP via the Sejm ELI JSON API') and resource ('Polish legal acts'), distinguishing it from siblings like 'isap_get_act' which likely retrieves a single act. It specifies the search mechanism and data source, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: for searching legal acts via the ELI API with specific filters. It distinguishes usage of 'title' vs. 'keyword' parameters, but does not explicitly mention when not to use it or name alternatives (e.g., 'isap_get_act' for retrieving a single act). The guidance is helpful but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it specifies the API type (JSON), pagination details, return format (raw JSON with structure), and platform requirement (BROWSER). However, it lacks details on rate limits or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by essential details in a logical flow (API usage, parameters, results). Every sentence adds value without redundancy, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is largely complete, covering purpose, usage, behavior, and parameters. It falls short of a 5 by not detailing error cases or response examples, which would enhance completeness for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters thoroughly. The description adds minimal value by noting that 'keyword' is required and 'platform' must stay BROWSER, but does not provide additional semantic context beyond what the schema offers, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Search Ninateka') and resources ('free VOD: films, docs, theatre, audio, etc.'), distinguishing it from siblings like 'ninateka_get_vod' by focusing on search functionality rather than retrieval of specific items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (searching Ninateka's content) and mentions a sibling tool ('ninateka_get_vod'), but does not explicitly state when to choose one over the other or list exclusions, keeping it from a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does an excellent job disclosing behavioral traits. It explains the return format ('Returns raw JSON: results[], pagination.maxCount, pagination.token'), pagination mechanics ('pass token as page_token for next page'), API characteristics ('No API key'), and important constraints ('Use accurate Polish strings; API matching is server-side'). The only minor gap is not explicitly stating this is a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise. Every sentence earns its place: first establishes purpose and data source, then explains return format and pagination, lists available resources, and ends with important usage notes. No wasted words, front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 15 parameters and no output schema, the description does remarkably well. It explains the return format, pagination, resource options, and important constraints. The main gap is the lack of output schema, but the description compensates by describing the JSON structure. Given the complexity, it could benefit from more explicit error handling or rate limit information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds some value by explaining parameter relationships: 'Optional city/voivodeship apply to institutions and branches' and clarifying that 'last_name' serves different purposes for employees vs publications. However, it doesn't significantly enhance understanding beyond what the comprehensive schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Query Polish POL-on registry data exposed by RAD-on Open Data API' with specific resources listed (institutions, branches, employees, projects, publications, courses). It distinguishes itself from siblings by specifying the exact data source (POL-on/RAD-on) and API characteristics, unlike generic search tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for querying specific Polish academic/scientific registry data. It mentions 'No API key' and 'Use accurate Polish strings; API matching is server-side' as important usage considerations. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It effectively discloses key behavioral traits: the tool is paginated, responses are large (implying performance considerations), and it has a 24-hour cache TTL. This covers important operational aspects beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by practical guidance and caching note. Every sentence earns its place with no wasted words, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no annotations and no output schema, the description is quite complete. It covers purpose, pagination behavior, performance considerations, and caching. The main gap is lack of detail on output format, but given the tool's relative simplicity, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters. The description adds marginal value by emphasizing 'Use small page_size' as a recommendation, but does not provide additional semantic context beyond what the schema already states about page_size and page_number.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('dump' implying list/retrieve) and resource ('common courts'), and specifies the content ('names, codes, divisions'). It distinguishes from siblings like 'saos_dump_judgments' or 'saos_dump_sc_chambers' by focusing on common courts specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage ('Use small page_size; responses are large') and mentions caching behavior ('Cache TTL 24h'), which helps guide when to use it. However, it does not explicitly state when not to use it or name specific alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it returns raw HTML, requires a session, and doesn't use KV cache. These are important operational details not inferable from the schema alone. It doesn't mention error handling or response structure, keeping it from a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences that each earn their place: first states the core functionality, second specifies the return format, third discloses session and caching behavior. No wasted words, front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only fetch tool with 100% schema coverage but no output schema, the description provides good context about what it returns (raw HTML) and operational constraints (session required, no cache). It could mention what the HTML contains or typical use cases, but given the tool's straightforward nature, it's mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline of 3. The description's mention of 'dokładnym numerze katalogowym' aligns with but doesn't expand on the schema's 'standard_number' description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Pobiera' - fetches/retrieves), the resource ('stronę szczegółów pojedynczej normy na WIEDZA' - details page of a single standard on WIEDZA), and the method ('po dokładnym numerze katalogowym' - by exact catalog number). It distinguishes from sibling 'wiedza_search_norms' which searches rather than fetches a specific item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when you have an exact catalog number from search results and need the detailed page. It doesn't explicitly state when NOT to use it or name alternatives, but the context is sufficiently clear given the sibling tools available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return format ('Returns JSON: title, authors, epochs, genres, download links...') and hints at data structure ('children volumes, optional fragment preview'), which is valuable. However, it doesn't mention error handling, rate limits, authentication needs, or whether this is a read-only operation, leaving some behavioral aspects unclear for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first clause, followed by return details and usage guidance. Every sentence adds essential information—no wasted words. It efficiently covers purpose, output, and sibling tool relationships in three concise sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no nested objects) and lack of output schema, the description does a good job of explaining what the tool does, what it returns, and how to use it with siblings. However, without annotations or output schema, it could benefit from more behavioral details (e.g., error cases, read-only nature) to be fully complete, though it's sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the parameter 'slug' well-documented in the schema. The description adds minimal value beyond the schema by providing examples ('e.g. lalka, pan-tadeusz') and context about slug sources ('from /katalog/lektura/{slug}/ or API href'), but doesn't explain semantics like format constraints or validation rules. With high schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch one book') and resource ('from Wolne Lektury'), distinguishing it from siblings like wolnelektury_filter_books (which filters) and wolnelektury_list_taxonomy (which lists categories). It specifies the retrieval mechanism ('by URL slug') and the scope ('one book'), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when to use this tool ('Fetch one book... by URL slug') and offers clear alternatives for discovering slugs ('via wolnelektury_list_taxonomy and wolnelektury_filter_books or from wolnelektury.pl catalog URLs'). This gives the agent direct guidance on when to use this tool versus its siblings for different tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the tool's behavior as a fetch operation that returns metadata and an embedded books list, but lacks details on error handling, rate limits, authentication needs, or response format. This is adequate for a read-only tool but misses some behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste: the first states the purpose and output, the second provides usage guidance. It is front-loaded with essential information and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple tool with one parameter (100% schema coverage), no output schema, and no annotations, the description is reasonably complete. It covers purpose, usage, and parameter context, but could improve by including more behavioral details like error cases or response structure, which are not critical for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the schema fully documenting the 'slug' parameter. The description adds minimal value by implying the slug comes from 'API or site URL' and referencing 'wolnelektury_list_taxonomy' for obtaining slugs, but doesn't provide additional syntax or format details beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch') and resource ('one thematic collection by slug') with explicit scope ('metadata + embedded books list'). It distinguishes from sibling tools by mentioning 'wolnelektury_list_taxonomy' for listing collections, avoiding redundancy with other WolneLektury tools like 'wolnelektury_get_book' or 'wolnelektury_filter_books'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when to use this tool ('Fetch one thematic collection by slug') and when to use an alternative ('Use wolnelektury_list_taxonomy with kind=collections to list collection slugs and titles'), offering clear guidance on tool selection and prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the return format ('JSON hits with title, URL, id, subtype'), error handling ('If the response is HTTP 403...'), and practical constraints ('origin WAF may block automated clients'). It doesn't mention rate limits or authentication requirements, but provides substantial behavioral context beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences that each serve distinct purposes: the first explains core functionality and return format, the second provides important error handling guidance. It's front-loaded with the main purpose and could be slightly more concise, but every sentence earns its place with valuable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no annotations and no output schema, the description provides substantial context: it explains the return format, distinguishes from sibling tools, and includes important error handling guidance. It doesn't explain pagination or result ordering, but covers the essential aspects well given the tool's complexity and lack of structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all three parameters thoroughly. The description adds minimal parameter semantics beyond what's in the schema - it mentions 'Polish keywords' for the query parameter, but this is already covered in the schema's description. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search'), target resource ('nac.gov.pl WordPress site (posts and pages)'), and method ('via REST API'). It distinguishes from siblings like 'nac_get_post' and 'nac_get_page' by explaining this tool returns search results while those tools retrieve specific content using IDs from these results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 versus alternatives: 'use `nac_get_post` / `nac_get_page` with that id' for retrieving specific content. It also includes important context about HTTP 403 errors and network retry strategies, which are practical usage considerations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the search is name-based ('by name fragment'), it's a read operation (implied by 'Search'), it uses pagination ('Pagination is 0-based'), and it specifies the return format ('Returns JSON (subject id, name, children ids, levels)'). However, it doesn't mention potential limitations like rate limits or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three sentences: purpose, usage guidance, and technical details. Each sentence earns its place by providing essential information without redundancy. The front-loaded purpose statement immediately clarifies the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no annotations and no output schema, the description provides good coverage: it explains the purpose, usage context, key behavioral aspects (pagination, return format), and references the API endpoint. However, it doesn't fully describe the JSON structure details or potential error cases, leaving some gaps in operational understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all 5 parameters thoroughly. The description adds minimal value beyond the schema, mentioning only that the 'name' parameter is a 'fragment of subject name' and that pagination is '0-based' (which is already in the schema). It doesn't provide additional context about parameter interactions or usage patterns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search BDL (GUS) thematic subjects by name fragment') and resource ('thematic subjects'), distinguishing it from sibling tools like bdl_search_units and bdl_search_variables. It explicitly mentions the goal of discovering subject IDs before other operations, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Use to discover subject IDs before listing variables or drilling into the tree'), providing clear context and purpose. It distinguishes this from other subject-related operations by framing it as a discovery step, though it doesn't name specific alternative tools for similar searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it specifies the API method (GET), pagination behavior (0-based), and that results can be used with another specific tool. However, it doesn't mention rate limits, authentication requirements, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly front-loaded with the core purpose in the first sentence, followed by usage guidance and technical details. Every sentence earns its place with no wasted words, making it highly efficient for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 7 parameters and no output schema, the description provides good context about what the tool returns (unit IDs for use with another tool) and how pagination works. However, without an output schema, it doesn't describe the structure of search results, which would be helpful for a complex search operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 7 parameters thoroughly. The description adds minimal value beyond the schema by mentioning 'optional level and year filters' and 'pagination is 0-based' (which the schema also covers). Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and resource ('BDL territorial units') with specific examples (voivodeships, counties, etc.). It distinguishes from sibling tools by specifying this searches units by name fragment, unlike bdl_search_subjects or bdl_search_variables which search different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Search BDL territorial units... by name fragment') and provides a clear alternative for what to do with results ('Use returned unit id with bdl_get_data_by_unit'). It also mentions optional filters (level and year) and pagination details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully describes key behavioral traits: the search functionality, pagination behavior (0-based), and the relationship to other tools. However, it doesn't mention rate limits, authentication requirements, or error handling, which would be helpful for a complete behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured in just two sentences. The first sentence covers purpose and main filters, the second covers usage of results and technical details (API endpoint and pagination). Every word earns its place with no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 8 parameters, 100% schema coverage, but no output schema, the description provides good contextual completeness. It explains the tool's purpose, usage guidelines, and key behavioral aspects (pagination). However, without an output schema, it doesn't describe the structure of search results, which would help the agent understand what to expect from the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description adds some context about filtering by 'name text (N1…N5), subject-id, level, and years' but doesn't provide additional semantic meaning beyond what's already in the parameter descriptions. This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verb ('Search') and resource ('BDL statistical variables (characteristics)'), and distinguishes it from siblings by mentioning that results' numeric IDs are used with specific sibling tools (bdl_get_data_by_variable and bdl_get_data_by_unit). This provides clear differentiation from other search tools in the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (to search variables) and provides clear alternatives for what to do with the results (use with bdl_get_data_by_variable or bdl_get_data_by_unit). It also mentions the specific API endpoint (GET /variables/search), which provides implementation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool returns 'raw XML', explains the two metadata formats (oai_dc vs jats) and their trade-offs, and mentions pagination via 'resumption_token'. However, it doesn't cover rate limits, authentication needs, or error handling, which would be helpful for a harvesting tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three sentences: first clarifies purpose and distinction from sibling, second explains usage scenarios, third details output format and metadata options. Every sentence earns its place with zero waste, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a harvesting tool with 6 parameters, 100% schema coverage, and no output schema, the description is mostly complete. It covers purpose, usage guidelines, output format (raw XML), and metadata options. However, without annotations, it could benefit from mentioning rate limits or authentication requirements, which are common for API-based harvesting tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters thoroughly. The description adds minimal value beyond the schema: it mentions 'optional date range' and 'OAI set (journal id from ListSets)', but doesn't provide additional syntax or format details. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs an 'OAI-PMH ListRecords harvest for Biblioteka Nauki' and explicitly distinguishes it from 'full-text keyword search', naming the sibling tool 'bn_search_publications' for that purpose. It specifies the verb (harvest/list), resource (records), and scope (Biblioteka Nauki).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 ('to list records by optional date range and/or OAI set, or to page with resumption_token') and when not to use it ('NOT full-text keyword search'), with a clear alternative named ('bn_search_publications'). It also clarifies the absence of a query string in OAI-PMH.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool 'Uses the public JSON search API (same as the website)' and 'Returns JSON with hits, snippets (mainTitleSnippets, fullTextSnippets), and totalResults,' which provides useful behavioral context about the API source and return format. However, it doesn't mention rate limits, authentication needs, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three sentences: purpose, usage guidelines, and return format. Each sentence adds distinct value without redundancy, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 9 parameters and no output schema, the description provides good context: purpose, usage guidelines, API source, and return format. It doesn't explain error cases or pagination details, but given the schema's thorough parameter documentation, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 9 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, such as explaining query syntax or publication_type nuances. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'Full-text search in Biblioteka Nauki (Polish open-access articles, books, chapters)' with specific resources mentioned. It distinguishes from sibling 'bn_search_articles' by specifying 'Prefer this tool when the user gives keywords, topics, author names, or titles' versus 'For harvesting by date range or OAI journal set without keywords' for the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 ('Prefer this tool when the user gives keywords, topics, author names, or titles') and when to use an alternative ('For harvesting by date range or OAI journal set without keywords, use bn_search_articles (OAI-PMH XML) instead'). This directly addresses sibling tool differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool returns HTML format, explains parameter sourcing from search results, clarifies the stability of the results ('Stable per record'), and mentions caching suitability. However, it doesn't address potential error conditions, rate limits, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with three sentences that each serve distinct purposes: stating the core functionality, explaining parameter usage, and describing behavioral characteristics. Every sentence earns its place with no wasted words, and the most critical information appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, 100% schema description coverage, but no output schema, the description provides good contextual completeness. It explains the HTML return format, parameter sourcing, result stability, and caching suitability. The main gap is the lack of information about the output structure or format details, which would be helpful since there's no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some contextual value by explaining that parameters should be copied from 'item-global links from bs_sejm_search results' and that 'sub_library is usually BS for main stacks', but doesn't provide significant additional semantic information beyond what's already in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verb ('Fetch') and resource ('one Sejm Library OPAC bibliographic record as HTML'), and explicitly distinguishes it from sibling tools by referencing 'bs_sejm_search results' and contrasting with 'session-bound full-set-set links'. This provides clear differentiation from other tools in the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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: 'Pass doc_library and doc_number exactly as in item-global links from bs_sejm_search results' and 'sub_library is usually BS for main stacks — copy from the link if different'. It also provides context about when not to use alternatives: 'Stable per record (unlike session-bound full-set-set links); suitable for caching' which helps distinguish it from other potential approaches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it returns 'raw HTML search results page' (not JSON), clarifies there is 'no public JSON API,' and outlines the search_type options. However, it lacks details on error handling, rate limits, or authentication needs, which would be beneficial for a tool interacting with an external database.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first states the purpose and output format, the second provides usage guidelines and references to sibling tools. Every sentence adds critical information without redundancy, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (searching an external photo database with raw HTML output) and lack of annotations or output schema, the description is largely complete. It covers purpose, output format, search options, and sibling tool integration. However, it could improve by mentioning potential limitations like result structure or error scenarios, which are relevant for a tool without structured output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by mentioning search_type options in Polish (e.g., 'tytul (film title)'), but does not provide additional syntax, format, or usage context for parameters. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search the Fototeka photo database (Polish cinema stills and production photos, Filmoteka Narodowa).' It specifies the verb ('search'), resource ('Fototeka photo database'), and scope ('Polish cinema stills and production photos'), distinguishing it from sibling tools like fototeka_get_photo by focusing on search rather than retrieval of individual records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 vs. alternatives: 'Use fototeka_get_photo with a numeric id from links pl/foto/view/{id}.html for one record.' This clearly directs users to the sibling tool for retrieving individual photos after obtaining IDs from search results, establishing a workflow and preventing misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key behavioral traits: it parses HTML (not using a JSON API), matches form parameters, and returns URLs with slugs for follow-up retrieval. However, it doesn't mention pagination behavior, error handling, or rate limits, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with essential purpose, followed by specific usage notes and parameter context. Every sentence adds value: first sets context, second explains technical implementation, third details parameters, fourth guides next steps. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no annotations and no output schema, the description is quite complete. It covers purpose, technical constraints, parameter usage, and integration with sibling tools. However, it lacks details on output format (e.g., structure of search results) and potential limitations like timeouts or result count, which could be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing clear documentation for all parameters. The description adds minimal value beyond the schema, only briefly mentioning that 'year_period' is optional and corresponds to form 'y', which is already implied by the schema. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches a specific photo archive (Fototeka Śląska) with details about the content (rural Silesia/Opole region historical photos) and technical context (WordPress site, HTML parsing). It distinguishes from its sibling 'fototekaslaska_get_photo' by specifying it's for search versus retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (searching the archive) versus the alternative ('fototekaslaska_get_photo' for retrieving specific photos using slugs from results). Also provides guidance on optional parameters like omitting 'year_period' to search all periods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: returns raw HTML with poster thumbnails and links, uses a non-JSON API (GET form), and requires parsing numeric IDs from results for use with gapla_get_poster. This covers output format, API type, and integration details, though it lacks information on rate limits or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three sentences: first states the purpose and scope, second explains the API format and output, third details parameter enums and integration. Every sentence adds essential information with zero waste, making it front-loaded and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description does well by explaining the raw HTML output, API constraints, and integration with gapla_get_poster. It covers the tool's complexity adequately, though it could mention pagination behavior or error cases for a more complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters. The description adds minimal value by briefly explaining the 'typ' and 'sort' enums in Polish terms, but doesn't provide additional semantics beyond what the schema already specifies. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches the Gapla film poster gallery, specifying it covers Polish and international film posters and festival materials. It distinguishes from sibling tools by mentioning the specific gallery (Filmoteka Narodowa) and referencing gapla_get_poster as a related tool, making the purpose specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (searching the Gapla gallery) and when to use an alternative (gapla_get_poster for retrieving specific posters by ID). It also mentions the tool uses the same GET form as the website, providing clear context for its operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it's a read-only retrieval operation (implied by 'retrieve'), returns JSON with specific data fields (water level, flow rate, etc.), covers all active stations in Poland, and notes the data refresh rate (~hourly). It lacks details on error handling or rate limits, but covers core operational aspects well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first clause, followed by additional details in two clear sentences. Every sentence adds value: the first states what it does and returns, the second specifies data freshness. There is no wasted text or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple retrieval with no parameters), no annotations, and no output schema, the description is mostly complete: it explains the purpose, data format, scope, and refresh rate. It lacks details on output structure (e.g., JSON schema) or error cases, but for a zero-parameter tool, this is sufficient though not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description adds no parameter-specific information, which is appropriate since no parameters exist, but it doesn't detract from the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('retrieve', 'returns') and resources ('current hydrological station readings', 'all active hydrological stations in Poland'). It distinguishes itself from sibling tools like imgw_meteo, imgw_synop, and imgw_warnings by specifying it deals with hydrological data rather than meteorological, synoptic, or warning data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('retrieve current hydrological station readings'), and the data source and refresh rate are specified. However, it does not explicitly state when not to use it or name alternatives among siblings (e.g., imgw_meteo for weather data), which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the data source (danepubliczne.imgw.pl), return format (JSON with specific measurement types), scope (all active meteorological stations in Poland), and refresh rate (roughly every hour). It doesn't mention error handling or authentication needs, but covers the essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise and front-loaded: the first sentence states the core purpose, the second adds details about return format and scope, and the third provides refresh information. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is nearly complete. It explains what data is returned, from where, for what geographic scope, and how frequently it's updated. The only minor gap is the lack of output schema, but the description adequately describes the return content (JSON with specific measurements).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, focusing instead on what the tool does without inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('retrieve', 'returns') and resources ('current meteorological station readings from IMGW-PIB', 'JSON with temperature, precipitation, snow cover, wind, and related measurements'). It distinguishes itself from siblings like imgw_hydro, imgw_synop, and imgw_warnings by specifying it provides station readings rather than hydrological data, synoptic data, or warnings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to get current meteorological station readings for Poland, refreshed roughly every hour. It doesn't explicitly state when not to use it or name alternatives, but the specificity of the data (station readings vs. hydro/synop/warnings) implies differentiation from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that it fetches 'public detail' (implying read-only access), describes the return format ('compact JSON object'), and mentions an alternative human-readable page via profileUrl. However, it doesn't mention potential limitations like rate limits, error conditions, or authentication requirements for a public API.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first states the purpose and key data elements, the second provides usage guidance and output format. Every element serves a clear purpose with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with no annotations and no output schema, the description is reasonably complete. It explains what data is returned, provides usage context, and mentions the human-readable alternative. However, without an output schema, it could benefit from more detail about the structure of the 'compact JSON object' being returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single parameter. The description adds value by explaining where the profile_id comes from ('from ludzie_search or ludzie_semantic_search') and providing context about its format ('e.g. jhMVc1vG5Yz'), though this example is also in the schema. With 0 parameters requiring additional semantics beyond schema coverage, baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch public detail'), target resource ('one Ludzie Nauki profile'), and key data elements (ORCID, academic degrees/titles, top keywords). It distinguishes this tool from its siblings ludzie_search and ludzie_semantic_search by focusing on retrieving detailed information for a single profile rather than searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: to get details for a single profile identified by profile_id from ludzie_search or ludzie_semantic_search. It provides clear alternatives by naming the sibling tools that should be used for searching rather than fetching individual profiles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool returns a ranked list of profiles, includes profileId and URLs, truncates large responses in summaries, and has a default limit (implied by 'Large responses are truncated'). However, it doesn't mention rate limits, authentication needs, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first states purpose and usage context, the second explains output behavior and optimization advice. Every phrase adds value without redundancy, making it easy to parse and front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no annotations and no output schema, the description does well by covering purpose, usage, output format (ranked list with profileId and URLs), and truncation behavior. However, it lacks details on response structure (e.g., fields beyond profileId/URLs) and error cases, which could be important given the complexity of semantic search.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 three parameters thoroughly. The description adds minimal value beyond the schema, only reinforcing that 'full_query' can be narrowed for exhaustive results. No additional syntax, format, or usage details are provided beyond what's in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs semantic/full-text search on Ludzie Nauki profiles, specifying the target resource (profiles on ludzie.nauka.gov.pl) and distinguishing it from simple surname searches by mentioning research topics, keywords, or natural-language queries. It explicitly differentiates from sibling tools like 'ludzie_search' by emphasizing semantic capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 ('for research topics, keywords, or natural-language queries (not only surnames)') and when to narrow queries ('narrow full_query if you need exhaustive lists'). It also implicitly suggests an alternative ('ludzie_get_scientist' for detailed profile data) by mentioning profileId output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the output format ('raw XML') and source characteristics ('aktualności, WordPress'), but doesn't mention potential rate limits, authentication requirements, or error behaviors. It provides basic operational context but lacks comprehensive behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed sentences with zero waste. First sentence states purpose and output, second provides critical exclusion context. Every word earns its place, and the most important information (what it does) comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless RSS fetch tool with no output schema, the description provides sufficient context about what it returns (raw XML) and what it's not (archival catalogue). It could benefit from mentioning typical response structure or error cases, but covers the essential operational context well given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters and 100% schema description coverage, the baseline would be 4. The description appropriately doesn't discuss parameters since none exist, and instead focuses on what the tool does and returns, which is correct for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch'), resource ('NAC institutional news RSS 2.0 feed'), and format ('raw XML'), distinguishing it from siblings by explicitly contrasting with archival catalogues on other platforms. It provides precise scope and output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when NOT to use this tool ('This is not the digitized archival catalogue — that lives on szukajwarchiwach.gov.pl'), providing clear alternative context and preventing misuse. It defines the tool's specific domain versus other data sources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: the tool returns raw HTML with specific content (result list with titles, excerpts, update dates), uses 0-based pagination, and operates on the public website. However, it lacks details on rate limits, error handling, or authentication needs, which would be useful for a public search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded, with two sentences that efficiently convey purpose, output format, pagination, and usage alternatives. Every sentence adds critical information without redundancy, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is mostly complete. It covers purpose, output format, pagination, and usage context. However, it lacks details on response structure (e.g., HTML parsing guidance) and potential limitations (e.g., result limits, timeout behavior), which would enhance completeness for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters thoroughly. The description adds minimal semantic value beyond the schema, mentioning only 'pagination is 0-based' which relates to the 'page' parameter. This meets the baseline for high schema coverage without significant enhancement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('full-text search'), target resource ('Polski Komitet Normalizacyjny main website'), and scope ('via the public Solr-backed view'), distinguishing it from sibling tools like wiedza_search_norms for norms DB searches. It explicitly differentiates from alternatives, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 versus alternatives: it specifies that for PN search/details, use wiedza_search_norms/wiedza_get_standard, and for purchases, see sklep.pkn.pl. This clearly defines the tool's context and exclusions, helping the agent choose correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool returns raw XML, supports pagination via resumption_token, and filters by date/set. However, it doesn't mention rate limits, authentication requirements, or error handling, which would be helpful for a complete behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three sentences: purpose statement, parameter context, and usage differentiation. Every sentence earns its place by providing essential information without redundancy. It's appropriately sized and front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 5 parameters, 100% schema coverage, and no output schema, the description is reasonably complete. It covers the purpose, behavioral aspects (pagination, output format), and usage context. The main gap is the lack of output schema, but the description compensates by stating it returns 'raw XML,' which provides some guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters thoroughly. The description adds minimal value beyond the schema by mentioning date filtering and setSpec examples, but doesn't provide additional semantic context about parameter interactions or usage patterns. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search (harvest) RCIN metadata via OAI-PMH ListRecords.' It specifies the resource (RCIN metadata), the method (OAI-PMH ListRecords), and distinguishes it from siblings by noting it's for OAI API access rather than interactive website search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 vs. alternatives: 'For interactive keyword search on the website, use https://rcin.org.pl/dlibra/ — this tool exposes the OAI API only.' This clearly differentiates it from website-based search and indicates the tool's specific use case for API harvesting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it warns about potential large data size ('can be very large'), advises on performance optimization ('Prefer narrow...'), explains the purpose of 'since_modification_date' for incremental sync, and clarifies the 'with_generated' parameter. It lacks details on error handling or rate limits, but covers key behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: it starts with the core purpose, immediately provides critical usage tips, explains key parameters in context, and ends with a clear distinction from sibling tools. Every sentence adds value with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, no annotations, and no output schema, the description does well: it covers purpose, usage guidelines, and key behavioral traits. However, it lacks details on output format (e.g., structure of returned judgments) and error scenarios, which would be helpful given the complexity. It's mostly complete but has minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters. The description adds some context: it explains 'since_modification_date' as 'incremental sync' and 'with_generated' as 'include SAOS enrichment module fields,' but doesn't provide additional syntax or format details beyond the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'SAOS bulk dump of judgments (full records per row — can be very large).' It specifies the verb ('dump'), resource ('judgments'), and scope ('bulk' with 'full records per row'), distinguishing it from sibling tools like 'saos_search_judgments' by emphasizing it's for 'mirror/sync' rather than search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 vs. alternatives: 'Prefer narrow judgment_start_date/judgment_end_date and page_size 10–20' for performance, and 'Not a replacement for saos_search_judgments (different use case: mirror/sync).' It also advises on incremental sync with 'since_modification_date' and includes context for 'with_generated'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what the tool returns (hypermedia links to dump sub-services) and provides a documentation URL, but doesn't mention rate limits, authentication requirements, or what format the links are in. The description adds some context but lacks comprehensive behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first explains the tool's function, the second provides usage guidance and documentation reference. Every element serves a purpose with no wasted words, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no annotations and no output schema, the description provides good context: it explains what the tool returns (hypermedia links to specific sub-services), when to use it versus alternatives, and includes documentation reference. The main gap is lack of output format details, but overall it's reasonably complete for this tool type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage. The description appropriately doesn't discuss parameters since none exist, and it focuses on explaining what the tool does rather than parameter details. This meets the baseline expectation for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it's a bulk dump API entry that lists hypermedia links to specific dump sub-services (commonCourts, judgments, scChambers, enrichments, deletedJudgments). It uses specific verbs ('lists', 'dump') and distinguishes itself from sibling tools by mentioning saos_search_judgments as an alternative for different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 versus alternatives: it states 'For searching judgments without mirroring the full database prefer saos_search_judgments.' This clearly defines the boundary between this bulk dump entry point and the search-focused sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly indicates this is a read operation ('Retrieve'), but doesn't disclose behavioral aspects like rate limits, authentication requirements, error conditions, or response format. The description adds some context about UUID sourcing but lacks operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first sentence states purpose and method, the second provides crucial usage guidance. Every word serves a clear function, and the most important information (what the tool does) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description covers the essential purpose and usage flow well. It could be more complete by mentioning what 'full metadata' includes or the response format, but given the simplicity of the tool and clear sibling relationship, it's largely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds value by explaining the UUID parameter's source ('found in the 'uuid' field of uafm_search results'), providing practical context beyond the schema's format example. However, it doesn't elaborate on UUID validation or error handling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Retrieve full metadata'), target resource ('a single item in the University of Applied Sciences in Nowy Sącz Repository'), and method ('by its UUID'). It explicitly distinguishes from sibling tool 'uafm_search' by mentioning the UUID source, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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: after obtaining a UUID from 'uafm_search' results. It clearly indicates the alternative tool ('uafm_search') for the prerequisite step, creating a clear usage flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: the AND logic of filters, the API endpoint structure, the parent_only option for top-level works, and the performance warning about large JSON returns. It does not mention error handling or pagination, but covers most critical operational aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: it starts with the core purpose, explains API constraints, provides endpoint details, and ends with practical warnings. Every sentence adds value—no redundancy or fluff—and it's appropriately sized for a tool with five parameters and no annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (filtering with AND logic, multiple parameters) and lack of annotations or output schema, the description does well: it covers purpose, usage, behavioral traits, and performance considerations. It doesn't detail the output format or error cases, but provides sufficient context for effective use in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters. The description adds some context: it explains the parent_only parameter's effect ('top-level works only, no sub-volumes') and advises on filter combinations to avoid large responses. However, it doesn't provide additional syntax or format details beyond what the schema offers, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List books matching combined filters (AND).' It specifies the verb ('List'), resource ('books'), and scope ('matching combined filters'), distinguishing it from sibling tools like 'wolnelektury_get_book' (single book retrieval) and 'wolnelektury_list_taxonomy' (list taxonomy items).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Requires at least one filter' (prerequisite), 'API does not expose full-text search; this is the supported way to narrow the catalog' (context and alternative method), and 'Filtering only by kind_slug can return a large JSON (~1MB+); prefer adding author or epoch when possible' (performance optimization advice).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and adds valuable behavioral context: it discloses caching behavior ('Responses are cached 24h') and performance characteristics ('themes/collections are ~100KB'). While it doesn't mention error handling or authentication needs, it provides more than basic operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Perfectly front-loaded with the core purpose in the first clause, followed by usage guidance and behavioral notes. Every sentence earns its place: the first establishes purpose, the second provides usage context, and the third adds important operational details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with no output schema, the description provides excellent context: purpose, usage with siblings, caching, and data size warnings. The only minor gap is lack of output format details (though structure is implied by 'names, slugs, hrefs'), but overall it's highly complete for its complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a well-documented enum parameter. The description adds minimal value beyond the schema by listing the same enum values in parentheses, but doesn't provide additional semantic context about what each taxonomy category represents or when to choose one over another.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('reference data for discovery') with specific categories (authors, epochs, genres, kinds, themes, collections). It distinguishes from siblings by mentioning specific tools (wolnelektury_filter_books, wolnelektury_get_book, wolnelektury_get_collection) that use its output, establishing its role as a metadata provider rather than a book/collection fetcher.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('List reference data for discovery') and provides clear alternatives ('Use slugs with wolnelektury_filter_books or wolnelektury_get_book / wolnelektury_get_collection'), giving direct guidance on how outputs should be utilized with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well. It discloses key behavioral traits: returns raw HTML (not JSON), only first page of hits (pagination limitation), and that it calls the same form as the website (no public JSON API). It could mention error handling or rate limits, but covers essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and appropriately sized. First sentence establishes purpose, subsequent sentences provide usage guidance, parameter context, and limitations. Every sentence earns its place, though could be slightly more front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter search tool with no annotations and no output schema, the description provides good completeness. It explains what the tool does, how to use it, parameter semantics, output format (raw HTML), limitations, and relationship to sibling tool. Could mention authentication needs or exact HTML structure, but covers most essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds valuable semantic context beyond the schema: provides concrete examples for local_base (bis01, bis02, etc.), explains find_code options with meaning (WRD = all fields, WST = title, etc.), and clarifies that request uses 'same syntax as the OPAC search box'. This elevates the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search the Sejm Library Aleph OPAC'), resource ('books, serials, parliamentary materials'), and scope ('at bs.sejm.gov.pl'). It distinguishes from sibling tool bs_sejm_get_item by explaining this returns a hit list while get_item retrieves full bibliographic cards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('search... returns raw HTML: the short hit list') versus alternatives ('use bs_sejm_get_item for the full bibliographic card'). Also provides context about limitations ('Only the first page of hits is returned; narrow the query or use get_item after picking doc_number').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It effectively describes key traits: it returns a fixed JSON list (not dynamic), serves as a navigation aid (not a query), and has limitations (covers only specific periods and collections). However, it doesn't mention potential errors, response format details, or performance aspects like rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It uses three sentences: the first states the purpose, the second provides usage guidelines, and the third clarifies limitations. Each sentence adds essential information without redundancy, making it front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple, no parameters) and lack of annotations or output schema, the description is mostly complete. It explains the purpose, usage, and limitations. However, it doesn't detail the exact structure of the returned JSON list or error handling, which could be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%. The description appropriately notes there are no inputs by not discussing parameters, which is sufficient. A baseline of 4 is applied since no parameters exist, and the description doesn't need to compensate for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Returns a fixed JSON list of relative paths for the main medieval document series on dokumentyslaska.pl (menu „Dokumenty”: periods up to 1333).' It specifies the exact resource (medieval document series paths) and distinguishes it from sibling tools like dokumenty_slaska_get_page, which is used for different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 versus alternatives. It states: 'Use dokumenty_slaska_get_page with indeks* paths for a table of contents and dokument* for the full running text for that period.' It also clarifies exclusions: 'This is not a database query — only a navigation aid; other collections (monasteries, chronicles, etc.) use different folders — discover paths from the homepage HTML.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully describes key behavioral traits: it retrieves active warnings (not historical), returns JSON format, and specifies the content structure (alert levels, affected regions, hazard descriptions, validity periods). It doesn't mention rate limits, authentication needs, or potential errors, but provides substantial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first states the core purpose and return format, the second explains the parameter options with concrete examples. Every sentence adds value with zero wasted words, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 1 parameter with full schema coverage, no annotations, and no output schema, the description provides strong context about what the tool does, when to use it, and what it returns. It could be slightly more complete by mentioning the data source URL (danepubliczne.imgw.pl) earlier or potential limitations, but it covers the essential operational aspects well for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, so the baseline is 3. The description adds meaningful semantic context beyond the schema by explaining what 'meteo' and 'hydro' warnings specifically include (e.g., 'storms, frost, heat, wind' for meteo, 'flood and hydrological' for hydro), and clarifies that 'all' is the default behavior. This enhances understanding of parameter choices.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('retrieve active meteorological and/or hydrological warnings'), the resource ('issued by IMGW-PIB'), and distinguishes it from sibling tools like imgw_hydro and imgw_meteo by explaining it can fetch both types or either individually. It goes beyond just restating the name to explain the actual function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when-to-use guidance by explaining the three type options: 'meteo' for weather warnings, 'hydro' for flood/hydrological warnings, or 'all' for both (default). This gives clear context for selecting between this tool and its specialized siblings (imgw_hydro, imgw_meteo).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it returns XML, uses Aleph WWW query prefixes, and includes important server-side failure handling ('SRU gate configuration file is missing'). It doesn't mention rate limits or authentication requirements, but provides substantial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with zero waste. The first sentence establishes the core purpose, the second explains parameter syntax with examples, and the third provides crucial error handling guidance. Every sentence earns its place by adding essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 2 parameters, 100% schema coverage, and no output schema, the description provides excellent context about the search mechanism, parameter usage, and failure scenarios. The only minor gap is the lack of information about the XML response structure, but given the technical nature of the tool and the schema coverage, this is reasonable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds significant value by explaining the 'request' parameter's syntax ('uses Aleph WWW query prefixes') and providing concrete examples ('wrd=kardiologia', 'wti=title words', 'wau=author') that clarify the parameter's purpose beyond the schema's basic description. It also references external documentation ('see Ex Libris X-Services introduction').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search the SUM (ŚUM Katowice) Aleph catalogue via X-Server `op=find`') and resource ('returns XML'), distinguishing it from sibling tools like 'sum_aleph_present' which serves a different purpose. It provides precise technical context about the search operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (for searching via X-Server `op=find`) and when not to use it (if the response contains 'SRU gate configuration file is missing'), providing a clear alternative ('sum_aleph_present may still work for sets'). This gives specific guidance on server failure scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does an excellent job disclosing key behavioral traits: it explains the static nature of the content, provides specific file naming conventions, mentions encoding (iso-8859-2), describes the return format (raw HTML), and explains how to navigate to related content. The only minor gap is not explicitly stating this is a read-only operation, though 'Fetch' strongly implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and front-loaded: the first sentence establishes the core purpose, subsequent sentences provide essential context and constraints, and every sentence earns its place with specific, actionable information. There is zero wasted verbiage while maintaining complete clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no annotations and no output schema, this description provides exceptional completeness. It covers the tool's purpose, when to use it, behavioral characteristics, parameter semantics, encoding information, return format, and navigation strategy. Given the complexity of accessing a static site with specific conventions, this description leaves no significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the context of the path parameter: it provides concrete examples ('indeks 1200.html', 'kamenz/index.html'), clarifies that spaces in filenames are acceptable, and explains what types of files serve what purposes (indeks*.html for tables of contents, dokument*.html for compilations). This goes well beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch a single page') and resource ('Dokumenty Śląska static site'), with explicit mention of content types (medieval Silesian documents, regesta, seals, iconography). It distinguishes this tool from its only sibling (dokumenty_slaska_medieval_catalog) by specifying this is for fetching HTML pages rather than catalog data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 ('There is no public search API — content is static HTML'), when to use specific file patterns ('use indeks*.html for tables of contents and dokument*.html for full compilations'), and how to navigate content ('Follow links from the response to load further pages'). It clearly establishes this as the primary access method for this static site.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![polish-academic-mcp MCP server](https://glama.ai/mcp/servers/asterixix/polish-academic-mcp/badges/card.svg)](https://glama.ai/mcp/servers/asterixix/polish-academic-mcp)

Score Badge

Copy to your README.md:

[![polish-academic-mcp MCP server](https://glama.ai/mcp/servers/asterixix/polish-academic-mcp/badges/score.svg)](https://glama.ai/mcp/servers/asterixix/polish-academic-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/asterixix/polish-academic-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server