Lawstronaut
Server Details
Connect AI to millions of laws and court cases with the Lawstronaut MCP.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4/5 across 16 of 16 tools scored. Lowest: 3.3/5.
The list_* tools are clearly distinct by entity type, but the retrieval tools (evidence_pull, get_document_text, get_markdown, get_source_url) have overlapping functionality. For example, both evidence_pull and get_document_text can return full text, and evidence_pull also provides a signed URL like get_source_url. This could confuse an agent selecting the appropriate tool.
The list_* tools follow a consistent verb_noun pattern, but the other tools mix conventions: get_document_text, get_document_with_version, get_markdown, get_source_url use 'get_', while evidence_pull and horizon_scan deviate. The inconsistent naming across the set reduces predictability.
With 16 tools, the server covers a comprehensive set of operations for legal document retrieval, including listing hierarchical entities, retrieving full text and metadata, and scanning recent changes. The scope is appropriate for a legal research tool, neither too sparse nor overly numerous.
The server provides extensive filtering and retrieval capabilities, but it lacks a free-text search tool. Users cannot search documents by keyword or phrase, which is a notable gap for legal research. The existing filters (title, tags, etc.) partially mitigate this but do not fully replace full-text search.
Available Tools
16 toolsevidence_pullARead-onlyIdempotentInspect
"Show me the source." For a specific document, return the full citation chain in one call: metadata (with all dates and identifiers), permanent legal_link, signed URL to the original source file (if available), and the full document body in markdown or plain text. Designed for auditability.
| Name | Required | Description | Default |
|---|---|---|---|
| iso | Yes | Document's jurisdiction ISO code, e.g. 'IE', 'NL', 'US', etc. | |
| document_id | Yes | Numeric document_id from any listing/search tool | |
| text_format | No | 'markdown' (preserves structure) or 'plain'. | markdown |
| include_text | No | Fetch the full body (default True) | |
| include_source_url | No | Fetch a temporary signed URL to the original file (PDF etc.) where available (default True). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description correctly focuses on what the tool returns rather than safety. It adds that the signed URL is temporary and the body is in markdown/plain text, which is useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starting with the memorable phrase 'Show me the source.' and then listing the key capabilities in one sentence. No wasted words, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately lists the expected outputs (metadata, link, signed URL, body). It covers the optional parameters (text_format, include_text, include_source_url) and the fact that the signed URL is temporary. It could mention pagination or size limits, but for a tool with few parameters, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have descriptions in the schema (100% coverage), so the description does not need to add much. It reinforces that iso and document_id identify the document, but does not add new meaning beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'the full citation chain in one call' including metadata, legal_link, signed URL, and document body. It positions itself as a comprehensive retrieval tool for auditability, differentiating from sibling tools like get_document_text or get_source_url which serve narrower purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says to use when you need full evidence for a document and 'designed for auditability'. This gives a clear usage context. However, it does not explicitly list when to prefer siblings (e.g., for just text use get_document_text), so it slightly misses in providing explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_document_textARead-onlyIdempotentInspect
Retrieves full text for a specific jurisdiction and optional filters. Use this tool when: - The user asks about available full text for a portal name, title, section_title, url, status, repealed, publication_date and crawling_date - The user wants to filter full text for type of authority, issuing authority, source identifier, source secondary identifier, tag Parameters: - iso (required): Filter by Jurisdiction ISO code (e.g. "US"). - portal (optional): Filter by portal name. - limit (optional): Number of results to return. - offset (optional): Number of results to skip. - document_id (optional): Filter by document ID. - repealed (optional): Filter by repealed status. - title (optional): Filter by title. - section_title (optional): Filter by section title. - url (optional): Filter by URL. - status (optional): Filter by status. - crawling_date (optional): Filter by crawling date. - last_updated (optional): Filter by last updated date. - last_amendment (optional): Filter by last amendment date. - publication_date (optional): Filter by publication date. - expiration_date (optional): Filter by expiration date. - effective_date (optional): Filter by effective date. - date_of_enactment (optional): Filter by date of enactment. - date_of_decision (optional): Filter by date of decision. - file_data_only (optional): Return file data only. - issuing_authority (optional): Filter by issuing authority. - type_of_authority (optional): Filter by type of authority. - source_identifier (optional): Filter by source identifier. - source_secondary_identifier (optional): Filter by secondary source identifier. - tag (optional): Filter by tag. - lang (optional): Filter by language. Returns: - Content full text list with document_id, full_text
| Name | Required | Description | Default |
|---|---|---|---|
| iso | Yes | Filter by Jurisdiction ISO code (e.g. 'US') | |
| tag | No | Filter by tag | |
| url | No | Filter by URL | |
| lang | No | Filter by language | |
| limit | No | Number of results to return | |
| title | No | Filter by title | |
| offset | No | Number of results to skip | |
| portal | No | Filter by portal name | |
| status | No | Filter by status | |
| version | No | Filter by version | |
| repealed | No | Filter by repealed status | |
| document_id | No | Filter by document ID | |
| last_updated | No | Filter by last updated date | |
| crawling_date | No | Filter by crawling date | |
| section_title | No | Filter by section title | |
| effective_date | No | Filter by effective date | |
| file_data_only | No | Return file data only | |
| last_amendment | No | Filter by last amendment date | |
| expiration_date | No | Filter by expiration date | |
| date_of_decision | No | Filter by date of decision | |
| publication_date | No | Filter by publication date | |
| date_of_enactment | No | Filter by date of enactment | |
| issuing_authority | No | Filter by issuing authority | |
| source_identifier | No | Filter by source identifier | |
| type_of_authority | No | Filter by type of authority | |
| source_secondary_identifier | No | Filter by secondary source identifier |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that it returns a list with document_id and full_text, but does not disclose other behavioral traits like pagination limits, error handling, or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first part is concise, but the inclusion of a full parameter list (already in the schema) makes the description longer than necessary. The structure is clear but could be more succinct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 26 parameters and no output schema, the description explains the return format but lacks details on parameter interactions, pagination behavior, and edge cases (e.g., no results). Somewhat complete but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description provides no additional meaning beyond the schema. Repeating parameter names and descriptions in the tool description is redundant but not harmful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieves full text for a specific jurisdiction and optional filters' and provides specific use cases ('Use this tool when: ...'), making the purpose unambiguous and distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use this tool with concrete user scenarios. However, it does not mention when not to use it or suggest alternative tools among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_document_with_versionARead-onlyIdempotentInspect
Retrieves a specific document with a specific version. Use this tool when: - The user wants to find a specific document with a specific version - The user asks about available a specific document with a specific version
Parameters:
- document_id (required): Document ID.
- version (required): Version.
Returns:
- Content with version with title, section_title, publication_date, effective_date, expiration_date, date_of_enactment, date_of_last_amendment, date_of_repealed, date_of_decision, status, version, source_identifier, source_secondary_identifier, issuing_authority, type_of_authority, language, legal_link, repealed, metadata, summary, tags, source_keywords, crawling_date, portal, portal_name, last_updated
- Only returns content that has crawled data with the specific version| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | Version | |
| document_id | Yes | Document ID |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, etc. The description adds value by specifying that only content with crawled data for the given version is returned, and it lists the return fields. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and usage. The list of return fields is lengthy but organized. It is not overly verbose, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description compensates by listing return fields and noting a conditional behavior. For a simple retrieval tool with two required parameters, this provides sufficient completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are described in the schema with basic descriptions ('Document ID', 'Version'). Schema coverage is 100%. The description repeats these without adding additional semantic meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a document with a specific version. It uses a specific verb and resource, and distinguishes itself from siblings like get_document_text or list_documents by emphasizing version specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use the tool ('when the user wants to find a specific document with a specific version'). It does not mention when not to use or alternatives, but the guidance is clear and context-specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_markdownBRead-onlyIdempotentInspect
Retrieves markdown for a specific jurisdiction and optional filters. Use this tool when: - The user asks about available markdown for a portal name, title, section_title, url, status, repealed, publication_date and crawling_date - The user wants to filter markdown for type of authority, issuing authority, source identifier, source secondary identifier, tag Parameters: - iso (required): Filter by Jurisdiction ISO code (e.g. "US"). - portal (optional): Filter by portal name. - limit (optional): Number of results to return. - offset (optional): Number of results to skip. - document_id (optional): Filter by document ID. - repealed (optional): Filter by repealed status. - title (optional): Filter by title. - section_title (optional): Filter by section title. - url (optional): Filter by URL. - status (optional): Filter by status. - crawling_date (optional): Filter by crawling date. - last_updated (optional): Filter by last updated date. - last_amendment (optional): Filter by last amendment date. - publication_date (optional): Filter by publication date. - expiration_date (optional): Filter by expiration date. - effective_date (optional): Filter by effective date. - date_of_enactment (optional): Filter by date of enactment. - date_of_decision (optional): Filter by date of decision. - file_data_only (optional): Return file data only. - issuing_authority (optional): Filter by issuing authority. - type_of_authority (optional): Filter by type of authority. - source_identifier (optional): Filter by source identifier. - source_secondary_identifier (optional): Filter by secondary source identifier. - tag (optional): Filter by tag. - lang (optional): Filter by language. Returns: - Content markdown list with document_id, content_markdown
| Name | Required | Description | Default |
|---|---|---|---|
| iso | Yes | Filter by Jurisdiction ISO code (e.g. 'US') | |
| tag | No | Filter by tag | |
| url | No | Filter by URL | |
| lang | No | Filter by language | |
| limit | No | Number of results to return | |
| title | No | Filter by title | |
| offset | No | Number of results to skip | |
| portal | No | Filter by portal name | |
| status | No | Filter by status | |
| version | No | Filter by version | |
| repealed | No | Filter by repealed status | |
| document_id | No | Filter by document ID | |
| last_updated | No | Filter by last updated date | |
| crawling_date | No | Filter by crawling date | |
| section_title | No | Filter by section title | |
| effective_date | No | Filter by effective date | |
| file_data_only | No | Return file data only | |
| last_amendment | No | Filter by last amendment date | |
| expiration_date | No | Filter by expiration date | |
| date_of_decision | No | Filter by date of decision | |
| publication_date | No | Filter by publication date | |
| date_of_enactment | No | Filter by date of enactment | |
| issuing_authority | No | Filter by issuing authority | |
| source_identifier | No | Filter by source identifier | |
| type_of_authority | No | Filter by type of authority | |
| source_secondary_identifier | No | Filter by secondary source identifier |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description does not need to restate those. It adds that the tool retrieves markdown and returns a list with document_id and content_markdown. However, it omits details on pagination behavior, ordering, or any side effects, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with sections for usage conditions and parameters, but it is verbose. The parameter list is redundant with the input schema and could be shortened. The essential information is front-loaded, but overall conciseness could be improved.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (26 parameters, no output schema), the description covers all filtering capabilities and states the return format (list with document_id and content_markdown). However, it lacks details on the structure of content_markdown, pagination details, and error handling, which are relevant for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a description. The description repeats these parameter descriptions in a bullet list, which provides no additional semantic value beyond the schema. It does not explain relationships between parameters or provide usage examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Retrieves markdown for a specific jurisdiction and optional filters,' which clearly states the tool's action and resource. It also lists many filter parameters, making the purpose specific. However, it does not explicitly differentiate from sibling tools like get_document_text, so it slightly lacks contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Use this tool when' bullet list that specifies scenarios where the tool is appropriate, such as when users ask about markdown with certain filters. But it does not advise when not to use it or compare with alternatives like get_document_text. The guidance is present but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_source_urlARead-onlyIdempotentInspect
Get a time-limited signed URL to the original source file (PDF etc.). Use this tool when: - The user wants to find a pdf URL for a specific document - The user asks about presigned URL for a pdf Parameters: - document_id (required): Document ID.
Returns:
- PDF URL for a specific document with document_id and pdf_url| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | Document ID |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: the URL is time-limited, and the return format is specified (document_id and pdf_url).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, well-structured with bullet points for usage and return value, and contains no unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, annotations covering safety, and no output schema, the description fully covers input, output, and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter description in the schema ('Document ID') matches the description's mention. The description adds no new semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: obtaining a time-limited signed URL for a source file, distinguishing it from sibling tools that return file content or metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use this tool when' scenarios are provided: finding a PDF URL or answering presigned URL queries. No explicit when-not cases, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
horizon_scanARead-onlyIdempotentInspect
Scans recent legal documents across jurisdictions. Use this when the user asks: - "What laws changed recently in Netherland?" - "Show me new regulations from last week" - "Any updates in NL law?"
| Name | Required | Description | Default |
|---|---|---|---|
| iso | Yes | One ISO code e.g. "IE", "NL", "US", etc. | |
| since | No | Freshness window. "yesterday", "today", "Nd"/"Nh"/"Nw" (e.g. "7d"), or ISO date "YYYY-MM-DD" | yesterday |
| topic | No | Optional filter (matches title) e.g. "employee monitoring" or "workplace surveillance" | |
| status | No | Optional filter on status field e.g. "new", "updated" String. | |
| date_field | No | Which date to window on. "crawling_date" (default) = when Lawstronaut crawled it. "publication_date" = when officially published. "last_updated" = when corpus record last changed. | crawling_date |
| include_repealed | No | If false, drop documents where repealed=true | |
| issuing_authority | No | Optional filter on issuing authority | |
| type_of_authority | No | Optional filter on type of authority | |
| max_per_jurisdiction | No | Max docs to return per jurisdiction (1-100) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context beyond annotations by specifying it scans legal documents across jurisdictions, with date windows and filters. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence explaining the tool, followed by a list of example queries. Every sentence is informative and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters with full schema coverage and no output schema, the description adequately explains the tool's purpose and usage scope. It could mention the return format, but the examples and parameter descriptions provide sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for all 9 parameters. The description does not add additional meaning beyond the schema, except for example usage. Baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it 'scans recent legal documents across jurisdictions', which is a specific verb+resource. Examples of user queries further clarify the purpose. It distinguishes from sibling tools like list_documents or get_document_text by focusing on recent scans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides three example user queries that indicate when to use the tool. However, it does not explicitly mention when not to use it or suggest alternative tools for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_authority_typesARead-onlyIdempotentInspect
Retrieves a list of authority types. Use this tool when: - The user wants to find legal authority types for a specific jurisdiction and optional filters - The user asks about available authority types for a portal name, authority type - The user wants to filter with pagination
Parameters:
- iso (required): Filter by Jurisdiction ISO code (e.g. "US").
- limit (optional): Number of results to return.
- offset (optional): Number of results to skip.
- portal_name (optional): Filter by portal name.
- authority_type (optional): Filter by authority type.
Returns:
- List of authority types with iso, authority_type, portal_name, pagination: total_count, limit, offset
- Only returns authority types that have data| Name | Required | Description | Default |
|---|---|---|---|
| iso | Yes | Filter by Jurisdiction ISO code (e.g. 'US') | |
| limit | No | Number of results to return | |
| offset | No | Number of results to skip | |
| portal_name | No | Filter by portal name | |
| authority_type | No | Filter by authority type |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying the return structure (fields: iso, authority_type, portal_name, pagination) and that only authority types with data are returned, which is beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with the purpose, followed by usage guidelines, parameters, and return information. Every sentence adds value with no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description fully explains the return structure and data filtering behavior. It covers all parameters, usage scenarios, and result characteristics, making it complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not add significant new meaning beyond what is already in the schema. It repeats parameter descriptions but does not provide additional constraints or examples beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of authority types with filtering options. It distinguishes from sibling list tools by specifying 'legal authority types' and providing usage scenarios, though it does not explicitly differentiate from similar list tools like list_issuing_authorities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use this tool when' section provides clear contexts for when to use the tool, such as finding authority types for a jurisdiction or filtering with pagination. However, it does not include when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_categoriesARead-onlyIdempotentInspect
Retrieves a list of categories for a specific jurisdiction and optional filters. Use this tool when: - The user wants to find legal categories for a specific jurisdiction and optional filters - The user asks about available categories for a subdomain id - The user wants to filter categories by name with pagination
Parameters:
- subdomain_id (optional): Filter by Subdomain ID.
- category_name (optional): Filter categories by name
- limit: z.number().optional().describe("Number of results to return"),
- offset: z.number().optional().describe("Number of results to skip")
Returns:
- List of categories with category_id, category_name, subdomain_id, domain_id, pagination: total_count, limit, offset
- Only returns categories that have data| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return | |
| offset | No | Number of results to skip | |
| subdomain_id | No | Filter by Subdomain ID | |
| category_name | No | Filter by category name |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. Description adds unique behavioral context: 'Only returns categories that have data' and details pagination behavior, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a clear purpose statement, usage guidelines in bullet points, a parameter list, and a return description. Each section is concise and front-loaded with the main action, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the return structure (list with fields and pagination) and the filter capabilities. Combined with annotations that indicate a safe, read-only operation, the description is sufficiently complete for an agent to understand and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 4 parameters described in schema). Description repeats parameter names and descriptions nearly verbatim, adding only 'optional' and 'filter by' which are already inferable. No additional semantics like format or constraints are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Retrieves a list of categories for a specific jurisdiction and optional filters', clearly identifying the resource and scope. It differentiates from siblings like list_subcategories by focusing on categories with jurisdiction context, though no explicit sibling comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description includes explicit 'Use this tool when:' with three bullet points (find legal categories, ask about available categories, filter by name with pagination). This guides the agent on appropriate contexts, though no explicit when-not-to-use instructions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_documentsARead-onlyIdempotentInspect
List documents in a jurisdiction with structured filters and pagination. Use this tool when: - The user wants to find legal content for a specific jurisdiction and optional filters - The user asks about available content for a portal name, title, section_title, url, status, repealed, publication_date and crawling_date - The user wants to filter content for type of authority, issuing authority, source identifier, source secondary identifier, tag Parameters: - iso (required): Filter by Jurisdiction ISO code (e.g. "US"). - portal (optional): Filter by portal name. - limit (optional): Number of results to return. - offset (optional): Number of results to skip. - document_id (optional): Filter by document ID. - repealed (optional): Filter by repealed status. - title (optional): Filter by title. - section_title (optional): Filter by section title. - url (optional): Filter by URL. - status (optional): Filter by status. - crawling_date (optional): Filter by crawling date. - last_updated (optional): Filter by last updated date. - last_amendment (optional): Filter by last amendment date. - publication_date (optional): Filter by publication date. - expiration_date (optional): Filter by expiration date. - effective_date (optional): Filter by effective date. - date_of_enactment (optional): Filter by date of enactment. - date_of_decision (optional): Filter by date of decision. - file_data_only (optional): Return file data only. - issuing_authority (optional): Filter by issuing authority. - type_of_authority (optional): Filter by type of authority. - source_identifier (optional): Filter by source identifier. - source_secondary_identifier (optional): Filter by secondary source identifier. - tag (optional): Filter by tag. - lang (optional): Filter by language. Returns: - Contents list with title, section_title, publication_date, effective_date, expiration_date, date_of_enactment, date_of_last_amendment, date_of_repealed, date_of_decision, status, version, source_identifier, source_secondary_identifier, issuing_authority, type_of_authority, language, legal_link, repealed, metadata, summary, tags, source_keywords, crawling_date, portal, portal_name, last_updated - Only returns content that has crawled data
| Name | Required | Description | Default |
|---|---|---|---|
| iso | Yes | Filter by Jurisdiction ISO code (e.g. 'US') | |
| tag | No | Filter by tag | |
| url | No | Filter by URL | |
| lang | No | Filter by language | |
| limit | No | Number of results to return | |
| title | No | Filter by title | |
| offset | No | Number of results to skip | |
| portal | No | Filter by portal name | |
| status | No | Filter by status | |
| version | No | Filter by version | |
| repealed | No | Filter by repealed status | |
| document_id | No | Filter by document ID | |
| last_updated | No | Filter by last updated date | |
| crawling_date | No | Filter by crawling date | |
| section_title | No | Filter by section title | |
| effective_date | No | Filter by effective date | |
| file_data_only | No | Return file data only | |
| last_amendment | No | Filter by last amendment date | |
| expiration_date | No | Filter by expiration date | |
| date_of_decision | No | Filter by date of decision | |
| publication_date | No | Filter by publication date | |
| date_of_enactment | No | Filter by date of enactment | |
| issuing_authority | No | Filter by issuing authority | |
| source_identifier | No | Filter by source identifier | |
| type_of_authority | No | Filter by type of authority | |
| source_secondary_identifier | No | Filter by secondary source identifier |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that the tool only returns content that has crawled data, which is a non-obvious behavioral constraint. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet lists and sections, but it is lengthy and repeats many parameter descriptions that are already in the schema. Some redundancy could be trimmed to improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 26 parameters and no output schema, the description covers return fields, pagination, and the constraint 'only returns content that has crawled data'. Could be slightly more explicit about pagination defaults and sort order, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description enumerates all parameters but does not add new meaning beyond the schema descriptions. It simply lists them in a structured way, which is adequate but not value-added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists documents in a jurisdiction with structured filters and pagination. The verb 'list' is specific, and the resource is defined as 'documents in a jurisdiction'. It distinguishes from sibling tools like 'get_document_text' which retrieves a single document's text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage scenarios: when user wants legal content for a jurisdiction with optional filters, or asks about available content for specific fields. Could improve by mentioning when not to use (e.g., if the user wants a single document, use 'get_document_text' instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_domainsARead-onlyIdempotentInspect
Retrieves a list of domains for a specific jurisdiction and optional filters. Use this tool when: - The user wants to find legal domains for a specific jurisdiction and optional filters - The user asks about available domains for a domain name - The user wants to filter with pagination
Parameters:
- domain (optional): Filter domains by name
- limit: z.number().optional().describe("Number of results to return"),
- offset: z.number().optional().describe("Number of results to skip")
Returns:
- List of domains with domain_id, domain, pagination: total_count, limit, offset
- Only returns domains that have data| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return | |
| domain | No | Filter by domain name | |
| offset | No | Number of results to skip |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: 'Only returns domains that have data' and describes the return format. It does not disclose authentication or rate limits, but overall provides useful extra information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear main sentence, a bulleted usage section, parameter list, and return description. It is front-loaded with the main purpose. Some bullet points are slightly redundant, but overall it is concise and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, parameters, and return format. However, it mentions 'jurisdiction' without a parameter, which is a notable gap. The return format is described adequately. Given the complexity (3 optional parameters, no output schema), the description is mostly complete but has an inconsistency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description mostly repeats schema descriptions for parameters. It adds a note that domain filter is optional, but also mentions 'jurisdiction' in the main description without a corresponding parameter, which is confusing. Minimal added value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a list of domains. The verb 'Retrieves' and resource 'domains' are specific. However, it mentions 'for a specific jurisdiction' but the input schema does not include a jurisdiction parameter, which may cause confusion. It does not explicitly differentiate from sibling tools like list_subdomains, but the name and first sentence are sufficient.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Use this tool when' section with three bullet points that clearly outline appropriate usage scenarios. It does not provide explicit when-not-to-use guidance or mention alternatives, but the given usage conditions are helpful and specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_issuing_authoritiesARead-onlyIdempotentInspect
Retrieves a list of issuing authorities for a specific jurisdiction and optional filters. Use this tool when: - The user wants to find legal issuing authorities for a specific jurisdiction and optional filters - The user asks about available issuing authorities for a portal name, issuing authority - The user wants to filter with pagination
Parameters:
- iso (required): Filter by Jurisdiction ISO code (e.g. "US").
- limit (optional): Number of results to return.
- offset (optional): Number of results to skip.
- portal_name (optional): Filter by portal name.
- issuing_authority (optional): Filter by issuing authority.
Returns:
- List of issuing authorities with iso, issuing_authority, portal_name, pagination: total_count, limit, offset
- Only returns issuing authorities that have data| Name | Required | Description | Default |
|---|---|---|---|
| iso | Yes | Filter by Jurisdiction ISO code (e.g. 'US') | |
| limit | No | Number of results to return | |
| offset | No | Number of results to skip | |
| portal_name | No | Filter by portal name | |
| issuing_authority | No | Filter by issuing authority |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable context: it only returns issuing authorities that have data and includes pagination details. This enhances transparency beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for usage, parameters, and returns. It is moderately concise, though it redundantly lists parameters separately from the body. Overall efficient and front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description sufficiently covers the return structure (including pagination fields) and behavioral constraints (returns only authorities with data). Completeness is adequate for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description repeats parameter descriptions but adds little new meaning beyond the schema; it mentions pagination behavior implicitly but not in structured detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of issuing authorities for a specific jurisdiction with optional filters, distinguishing it from sibling list tools (e.g., list_jurisdictions, list_authority_types) by focusing on issuing authorities and specifying required and optional parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use this tool when' scenarios, such as finding legal issuing authorities for a jurisdiction or filtering with pagination, but does not explicitly state when not to use it or offer alternatives, which keeps it just below perfect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_jurisdictionsARead-onlyIdempotentInspect
List all jurisdictions (countries/states) available in the Lawstronaut legal corpus. Call this FIRST when answering legal questions so you know which "iso" codes are valid for the other tools. Result is cached for the MCP process lifetime
Returns: {data: [{"name": "Belgium", "iso": "BE", "type": "country"}, ...]}
- Full list of jurisdiction objects including names, iso, and type| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that results are cached for the MCP process lifetime and specifies the return format, giving extra behavioral context without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences covering purpose, usage guidance, and return format. Every sentence adds value, and the structure is front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, clear annotations), the description fully covers what the tool does, when to use it, and what it returns. No gaps remain for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per the guidelines the baseline score is 4. The description does not need to add parameter semantics, and it provides sufficient context for parameter-free invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'jurisdictions (countries/states) available in the Lawstronaut legal corpus'. It clearly distinguishes from sibling tools that list other entities like authority types, categories, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Call this FIRST when answering legal questions so you know which "iso" codes are valid for the other tools,' providing clear when-to-use guidance and explaining its role as a prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_law_typesARead-onlyIdempotentInspect
Retrieves a list of law types for a specific jurisdiction and optional filters. Use this tool when: - The user wants to find legal law types for a specific jurisdiction and optional filters - The user asks about available law types for a subcategory id - The user wants to filter law types by name with pagination
Parameters:
- subcategory_id (required): Filter by Subcategory ID.
- law_type (optional): Filter law types by name
- limit: z.number().optional().describe("Number of results to return"),
- offset: z.number().optional().describe("Number of results to skip")
Returns:
- List of law types with law_type_id, law_type, subcategory_id, category_id, pagination: total_count, limit, offset
- Only returns law types that have data| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return | |
| offset | No | Number of results to skip | |
| law_type | No | Filter by law type name | |
| subcategory_id | Yes | Filter by Subcategory ID |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate safe read behavior (readOnlyHint, idempotentHint, non-destructive). The description adds value by stating 'Only returns law types that have data' and detailing return structure, beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise and front-loaded with the purpose. It includes a bullet list for parameters and returns, but could be more streamlined without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description adequately explains return fields and pagination. It covers the required parameter, optional filters, and a constraint (only law types with data). Sufficient for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters with descriptions (100% coverage). The description repeats the same info without adding new meaning, so it meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of law types with optional filters. It distinguishes from sibling list tools by specifying the resource (law types) and required parameter (subcategory_id). However, it mentions 'jurisdiction' which is not a parameter, causing slight confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases ('Use this tool when:'), helping agents decide when to invoke it. However, it does not mention when not to use it or explicitly differentiate from siblings like list_categories or list_subcategories.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_portalsARead-onlyIdempotentInspect
Retrieves a list of legal portals filtered by jurisdiction and optional criteria. Use this tool when: - The user wants to find legal portals, websites, or resources for a specific jurisdiction - The user asks about available portals in a country or state - The user wants to filter portals by name, language, or tag with total crawled links
Parameters:
- iso (required): Filter by Jurisdiction ISO code (e.g. "US").
- name (optional): Filter portals by name or URL keyword
- tag (optional): Filter portals by tag
- lang (optional): Filter portals by language name
Returns:
- List of portals with name, URL, language, jurisdiction, tags, and total crawled links
- Only returns portals that have crawled data| Name | Required | Description | Default |
|---|---|---|---|
| iso | Yes | Filter by Jurisdiction ISO code (e.g. 'US') | |
| tag | No | Filter by portal tags | |
| lang | No | Filter by language | |
| name | No | Filter by portal name |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, etc. The description adds value by stating 'Only returns portals that have crawled data,' which is a behavioral constraint not captured by annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections: general purpose, usage guidelines, parameter list, and return info. It is concise and front-loaded with the main action, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a filtered list tool with 4 parameters and no output schema, the description explains return fields and a constraint (crawled data). It is sufficient for an agent to use correctly, though it could mention pagination or limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents parameters. The description restates parameter info but adds context about returned fields, including 'total crawled links'. However, it doesn't significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it 'Retrieves a list of legal portals filtered by jurisdiction and optional criteria.' The verb 'Retrieves' and specific resource 'list of legal portals' are clearly defined, distinguishing it from sibling tools that list documents, categories, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases such as when a user wants to find legal portals for a jurisdiction or filter by name, language, or tag. However, it does not explicitly state when not to use this tool or mention alternatives, so it's slightly above average but not perfect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_subcategoriesARead-onlyIdempotentInspect
Retrieves a list of subcategories for a specific jurisdiction and optional filters. Use this tool when: - The user wants to find legal subcategories for a specific jurisdiction and optional filters - The user asks about available subcategories for a category id - The user wants to filter subcategories by name with pagination
Parameters:
- category_id (required): Filter by Category ID.
- subcategory_name (optional): Filter subcategories by name
- limit: z.number().optional().describe("Number of results to return"),
- offset: z.number().optional().describe("Number of results to skip")
Returns:
- List of subcategories with subcategory_id, subcategory_name, category_id, pagination: total_count, limit, offset
- Only returns subcategories that have data| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return | |
| offset | No | Number of results to skip | |
| category_id | Yes | Filter by Category ID | |
| subcategory_name | No | Filter by subcategory name |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds that only subcategories with data are returned, but does not mention ordering, error handling, or other behaviors. This provides some additional context beyond annotations, but not extensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear opening sentence, a use-case list, parameter table, and return format. It is concise and front-loaded, though the parameter listing is somewhat redundant with the schema. Overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately specifies return structure (subcategory_id, subcategory_name, category_id, pagination fields) and the constraint that only subcategories with data are returned. It covers the tool's purpose, usage, parameters, and output completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description lists parameters with descriptions that match the schema, offering no additional semantics. The note about 'only returns subcategories that have data' is not parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of subcategories for a specific jurisdiction, with optional filters. It uses a specific verb ('Retrieves') and specifies the resource and scope, distinguishing it from sibling tools like list_categories and list_jurisdictions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use this tool when:' bullet points listing scenarios such as finding legal subcategories for a jurisdiction or filtering by name with pagination. While it doesn't explicitly say when not to use it, the guidelines are clear and helpful, earning a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_subdomainsARead-onlyIdempotentInspect
Retrieves a list of subdomains for a specific jurisdiction and optional filters. Use this tool when: - The user wants to find legal subdomains for a specific jurisdiction and optional filters - The user asks about available subdomains for a domain id - The user wants to filter subdomains by name with pagination
Parameters:
- domain_id (required): Filter by Domain ID.
- subdomain (optional): Filter subdomains by name
- limit: z.number().optional().describe("Number of results to return"),
- offset: z.number().optional().describe("Number of results to skip")
Returns:
- List of subdomains with subdomain_id, subdomain, domain_id, pagination: total_count, limit, offset
- Only returns subdomains that have data| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return | |
| offset | No | Number of results to skip | |
| domain_id | Yes | Filter by Domain ID | |
| subdomain | No | Filter by subdomain name |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details: 'Only returns subdomains that have data' and explains pagination behavior. This adds value beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat structured with a first line, usage bullets, parameter list, and returns. However, the parameter list includes messy inline code (e.g., 'z.number().optional().describe(...)') which is not concise and detracts from readability. It could be more polished.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (4 parameters, 1 required, readOnlyHint), the description covers essential aspects: pagination, filtering, and the condition that only subdomains with data are returned. No output schema exists, but the returns section provides a useful summary. It is adequately complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description lists parameters with descriptions that mirror the schema, providing no additional semantic meaning beyond what is already in the structured input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a list of subdomains for a specific jurisdiction and optional filters. It specifies the resource (subdomains) and the action (retrieves), and later clarifies that the required parameter is domain_id. Although it mentions 'jurisdiction' initially, the context makes the purpose clear, and it distinguishes from siblings like list_domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Use this tool when' section with three specific scenarios, which gives clear guidance on when to invoke it. However, it does not explicitly exclude cases where other tools (e.g., list_domains) would be more appropriate, nor does it mention alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!