Lawstronaut
Server Details
Connect AI to millions of laws and court cases with the Lawstronaut MCP.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- Lawstronaut-FZCO/lawstronaut-mcp
- GitHub Stars
- 0
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.1/5 across 16 of 16 tools scored. Lowest: 3.1/5.
Most tools have distinct purposes, but evidence_pull and get_document_text both return full text, which could cause confusion. Other tools like list_documents and get_markdown are clearly differentiated.
Names follow a mix of 'list_', 'get_', and one-off names like 'evidence_pull' and 'horizon_scan'. The verb_noun pattern is present but inconsistent.
16 tools is reasonable for a legal document retrieval server, though some functionality overlaps (e.g., multiple ways to get document text). Still well-scoped for the domain.
Covers browse, filter, and retrieve operations comprehensively. Missing a general text search tool, but horizon_scan offers a recent-changes scan. Minor gap.
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, openWorldHint, idempotentHint, and destructiveHint; the description adds value beyond these by explaining the return components (metadata, link, URL, body) and noting conditional availability ('if available'). It does not contradict 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?
Three sentences, front-loaded with purpose, no wasted words. The informal quote 'Show me the source.' quickly conveys intent. Every sentence adds value.
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 5 parameters, no output schema, and annotations present, the description covers what is returned and hints at document_id source. It lacks explicit return structure or error handling, but is largely complete for the tool's 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 description coverage is 100%, so baseline is 3. The high-level description does not add significant detail beyond the schema; it groups the output but does not elaborate on parameter semantics like format or defaults.
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 that the tool returns the full citation chain for a specific document, including metadata, legal_link, signed URL, and body. This is a specific verb+resource combination and differentiates it from siblings like get_document_text or get_source_url by being a comprehensive single-call retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for auditability and when a full citation chain is needed, but does not explicitly name alternatives or state when not to use it. The sibling tools are listed but not compared, leaving the agent to infer context without direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_document_textBRead-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=true and destructiveHint=false, so the description does not need to restate those. The description adds the return format ('Content full text list with document_id, full_text') but does not disclose other behavioral traits like pagination behavior, rate limits, or data freshness. Given the annotations, the description provides adequate but not exhaustive transparency.
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 overly long (over 20 lines) and largely repeats the parameter list from the input schema. The bullet points of use cases are verbose and could be condensed. The front-loading is acceptable, but the redundancy reduces conciseness. A more streamlined version would be more effective.
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 26 parameters and no output schema, the description is incomplete. It lacks explanation of pagination (limit/offset behavior), the meaning of 'file_data_only', and details about the returned data structure beyond 'document_id, full_text'. The absence of an output schema increases the burden on the description, which is not fully met.
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 all parameters with brief explanations that mirror the schema. It adds no extra meaning beyond what the schema already provides, such as parameter interplay, formatting constraints, or edge cases. The 'Returns' section is helpful but does not enhance parameter semantics.
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 tool's purpose is clearly stated: 'Retrieves full text for a specific jurisdiction and optional filters.' It specifies the resource (full text) and action (retrieve), and implies it is a query tool. However, it does not explicitly differentiate from siblings like get_document_with_version or get_markdown, leaving the agent to infer that 'full text' is distinct.
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 bullet points listing when to use the tool (e.g., 'when the user asks about available full text for a portal name...'). This provides some guidance, but it does not mention when not to use it or compare it to sibling tools. The list is broad and somewhat redundant with the parameter list, offering limited strategic direction.
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 indicate read-only, idempotent, and non-destructive behavior. The description adds a useful behavioral constraint: 'Only returns content that has crawled data with the specific version,' providing transparency 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 well-structured with clear sections for function, usage, parameters, and returns. It is moderately concise, though the return field list is somewhat lengthy. Overall, it is front-loaded and informative.
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 specifying the crawled data condition. It covers the tool's core functionality but could mention error handling or missing versions for full 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?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description repeats parameter names and basic descriptions without adding meaningful extra semantics, meeting baseline expectations.
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 specific document with a specific version, using a specific verb and resource. It effectively distinguishes from sibling tools like get_document_text or get_source_url by focusing on version retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Use this tool when' section that clearly indicates the context (user wants a specific document with a specific version). However, it does not explicitly mention when not to use it or suggest alternatives, which would improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_markdownARead-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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about return format ('Content markdown list with document_id, content_markdown'), which is not in annotations. 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 conditions, but the parameter listing is lengthy and largely duplicates the schema. Could be more concise by omitting the parameter list or referencing the schema.
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 26 parameters and no output schema, the description adequately explains each parameter's purpose and the return content. It covers the tool's input and output sufficiently for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by listing all parameters in a readable format and describing the return structure, which the schema does not cover.
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 'Retrieves markdown for a specific jurisdiction and optional filters', providing a specific verb and resource. It distinguishes from sibling tools like get_document_text or get_source_url by focusing on markdown content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases: 'user asks about available markdown for portal name, title, section_title, url, status, repealed, publication_date and crawling_date'. However, it does not mention when not to use or alternatives, which slightly lowers the score.
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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by noting the URL is time-limited and signed, going beyond annotations. 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 fairly concise and front-loads the purpose. However, it includes a redundant bullet list for parameters that adds no new information, slightly reducing 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 single-parameter tool with good annotations and no output schema, the description adequately explains the tool's purpose, when to use it, and what it returns (PDF URL). Missing details about the time-limited nature are minor.
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% with one parameter (document_id) described as 'Document ID'. The description redundantly lists the same parameter without adding meaning beyond the schema, so no added value.
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 gets a time-limited signed URL to the original source file (PDF etc.), specifying the verb 'get' and resource 'source URL'. It distinguishes itself from sibling tools like get_document_text and get_markdown by focusing on the signed URL for the original file.
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:' bullets provide clear context: when the user wants a PDF URL or presigned URL for a specific document. However, it does not explicitly state when not to use this tool or mention alternatives.
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=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is covered. The description adds that it scans recent documents, but does not disclose further behavioral details like return format, pagination, or rate limits. It does not contradict 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 extremely concise: one sentence stating purpose followed by a short list of example queries. Every sentence is useful and immediately understandable. No 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?
With 9 parameters and no output schema, the description could do more to explain what the tool returns (e.g., list of document snippets or full documents). However, the 100% schema coverage and annotations partially compensate. It is adequate but not thorough.
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% (all parameters have descriptions in the JSON schema). The description's example queries hint at parameters (iso, since) but do not add meaning beyond what the schema already provides. 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 action ('scans recent legal documents') and the scope ('across jurisdictions'), and provides specific example queries that distinguish it from sibling tools like list_documents (which lists all documents) or evidence_pull (which focuses on specific evidence).
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 gives concrete example queries telling an agent when to invoke this tool (e.g., 'What laws changed recently in Netherland?'). It does not explicitly state when not to use it or mention alternatives, but the examples provide clear usage context.
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, and not destructive. Description adds useful behavioral detail: only returns authority types that have data. 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?
Well-structured with clear sections for usage, parameters, and returns. Not overly long, but could be slightly more concise by removing redundant parameter descriptions already in schema.
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 lacking an output schema, the description fully explains the return structure. Combined with annotations, it provides complete context for an agent to use the tool correctly.
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. Description repeats parameter descriptions but adds return format (pagination fields, fields returned), which provides additional context beyond 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?
Clearly states it retrieves a list of authority types, with specific filters. Distinguishes from sibling tools like list_jurisdictions and list_law_types by focusing on authority types for a jurisdiction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases for when to use this tool (e.g., finding legal authority types, filtering by portal/authority type). Does not mention when not to use it or provide alternatives, but context from siblings makes it clear.
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, openWorldHint, idempotentHint, and destructiveHint, establishing a non-destructive, safe read operation. The description adds value by noting that only categories with data are returned and explaining pagination behavior, which goes 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 front-loads the main purpose but includes a bulleted list of when-to-use scenarios and parameter descriptions. While informative, it is slightly verbose and could be more concise by merging the usage scenarios and removing redundant parameter list.
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 tool has no required parameters and provides full schema coverage. The description explains the return format (fields and pagination) and a key constraint (only categories with data). For a straightforward listing tool, this is sufficiently 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 description coverage is 100%, so the schema already documents all parameters. The description restates parameter purposes (e.g., 'Filter by Subdomain ID') but does not add significant new meaning or examples beyond the schema. Baseline of 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 'Retrieves a list of categories for a specific jurisdiction and optional filters.' It lists specific use cases and the tool name directly reflects its function. The sibling tools like list_subcategories and list_domains indicate distinct resource types, so no ambiguity.
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 that describe typical scenarios, such as finding categories for a subdomain or filtering by name. However, it does not specify when not to use it or suggest alternatives, which would improve guidance.
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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: it only returns content that has crawled data, and lists return fields. This supplements the annotations 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 lengthy due to parameter listing, but it is well-structured with a summary, usage conditions, parameter list, and return fields. It front-loads the core purpose. Some redundancy with schema descriptions exists, but the structure aids readability.
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 26 parameters and no output schema, the description compensates by listing return fields and noting the crawled-data constraint. It could be more specific about pagination behavior (limit/offset), but overall it is fairly 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 description coverage is 100%, so parameters are already documented in the schema. The description lists parameters with brief explanations (mostly 'Filter by X'), but also adds usage context (e.g., 'Returns only content that has crawled data') and lists return fields, adding 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 starts with a specific verb-resource pair 'List documents in a jurisdiction', clearly stating the action and scope. It distinguishes from sibling 'list_' tools that list other entities (e.g., list_authority_types) and from document retrieval 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 'Use this tool when:' conditions, providing clear context for when the tool is appropriate. It does not explicitly state when not to use it or mention alternatives, but the context is sufficient given the sibling tools.
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?
Description 'Retrieves' aligns with annotations' readOnlyHint=true, and adds behavioral detail like 'Only returns domains that have data' and pagination behavior, which are not in 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 structured but somewhat verbose, including a 'Parameters' section that largely duplicates the schema, and a 'Returns' section; could be 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?
Description provides a 'Returns' section compensating for no output schema, but introduces ambiguity with 'jurisdiction' which is not a parameter in the schema. Otherwise covers main usage and behavior.
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. Description repeats schema parameter descriptions but adds context about optionality and grouping, without adding new semantic meaning beyond 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 verb 'Retrieves' and resource 'list of domains', and specifies 'for a specific jurisdiction and optional filters', which distinguishes it from sibling tools like list_documents or 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 explicitly lists three use cases for when to use this tool, but does not mention when not to use it or alternative tools, though the context is clear.
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?
The description adds value beyond annotations by noting that it only returns issuing authorities that have data, and it details the return fields. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature, and the description is consistent with these.
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 points for parameters and returns, making it scannable. It front-loads the purpose but includes some redundancy (e.g., repeating parameter descriptions from schema). It is 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully documents the return format (list with iso, issuing_authority, portal_name, pagination). It covers all necessary context: purpose, when to use, parameters, and output, making it complete for agent selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all parameters described in the input schema. The description repeats these descriptions in a bullet list but adds no new semantic information compared to the schema. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a list of issuing authorities for a specific jurisdiction with optional filters. It specifies the verb 'Retrieves' and the resource 'issuing authorities', and distinguishes from sibling list tools by focusing on a different entity.
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 specific scenarios, providing clear context. However, it does not explicitly exclude alternatives among siblings or state when not to use it, missing the opportunity for complete guidance.
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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by disclosing that the result is cached for the MCP process lifetime and specifying the return structure, which goes 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 concise, with front-loaded purpose and usage instruction. Every sentence adds value: first sentence states purpose, second provides usage guidance, and the return format block is helpful without being excessive.
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 zero parameters, no output schema (but description provides return format), and comprehensive annotations, the description fully equips the agent with necessary context: when to call, what it returns, caching behavior, and relationship to other tools.
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 zero parameters, so schema coverage is 100%. With no parameters, the baseline score is 4. The description does not need to add parameter information but does provide return format details, which 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 uses a specific verb ('List') and resource ('jurisdictions (countries/states)') and clearly states the tool's role in the legal corpus context. It differentiates from sibling list tools by focusing on jurisdictions and their ISO codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to call this tool FIRST when answering legal questions to obtain valid ISO codes for other tools, providing clear when-to-use guidance. Also mentions caching behavior, which adds to usage context.
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 declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context by noting 'Only returns law types that have data' and describing pagination behavior (limit, offset), going 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 well-structured with sections for usage, parameters, and returns. It is front-loaded with the main purpose. However, it is slightly verbose in re-listing parameters with minimal added value.
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 scenarios, all parameters, and return format. Given no output schema and moderate complexity (4 params), it provides complete context for an agent to invoke the tool correctly.
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% with all parameters described. The description repeats the schema descriptions without adding new meaning, so it meets the baseline of 3 but does not exceed.
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 'Retrieves' and resource 'law types' with scoping 'for a specific jurisdiction and optional filters'. It clearly distinguishes from sibling tools like list_categories or list_authority_types by focusing on law types.
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 three usage scenarios under 'Use this tool when', providing clear context. However, it does not mention when not to use it or provide alternatives, so it loses one point.
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 indicate readOnly, idempotent, non-destructive. The description adds value by stating 'Only returns portals that have crawled data,' which is a behavioral filter not captured by 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?
Well-structured with a main sentence, bulleted use cases, and parameter list. No redundant or unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description lists return fields and notes the condition of crawled data. Lacks mention of pagination or limits, but adequate for a list tool with moderate 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% but the description adds meaning: for 'name' it says 'keyword' implying partial match, and groups parameters with filtering intent. This goes beyond schema descriptions with a baseline of 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?
The description clearly states the verb 'Retrieves a list' and the resource 'legal portals' with jurisdiction filtering. It distinguishes from sibling list_ tools (e.g., list_jurisdictions, list_documents) by focusing on portals and specific criteria.
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?
Three explicit 'Use this tool when:' bullets provide clear use cases. Does not state when not to use or name alternative tools, but the context is clear enough for an agent given sibling tools.
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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is well-covered. The description adds the behavioral note 'Only returns subcategories that have data' and describes the return structure, which provides additional 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 well-structured with sections for purpose, usage, parameters, and returns. It is a bit verbose (especially the parameter section which mirrors schema), but it front-loads the purpose and provides clear organization. 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 the tool's simplicity (4 parameters, no output schema, no nested objects) and comprehensive annotations, the description provides complete context: purpose, usage guidelines, parameter details, and return structure including pagination and the note about non-empty subcategories.
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 baseline is 3. The description repeats parameter descriptions but adds no new meaning beyond the schema. The returns section explains output structure but does not directly enhance parameter semantics.
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 subcategories for a specific jurisdiction with optional filters. It uses a specific verb 'retrieves' and identifies the resource 'subcategories'. The sibling tools include list_categories and list_jurisdictions, so this tool is properly differentiated as a subcategory list.
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 three use cases: when the user wants legal subcategories, when asking about available subcategories for a category id, and when filtering by name with pagination. It does not explicitly state when not to use or name alternatives, but the usage is clear and context is provided.
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?
Description adds value beyond annotations by stating 'Only returns subdomains that have data'. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, and description aligns with these. No 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?
Every sentence adds value. Front-loaded with purpose, followed by use case bullets, parameter table, and return description. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, description sufficiently explains return structure (fields, pagination) and behavioral filter. Context from parameters and annotations is well integrated.
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 baseline is 3. Description repeats parameter names and optionality as in schema, adding no significant new meaning. No added constraints or 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?
Description clearly states verb 'retrieves', resource 'list of subdomains', and scope 'for a specific jurisdiction and optional filters'. It effectively distinguishes from sibling tools like list_domains or list_subcategories.
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 bullet list of when to use: finding legal subdomains, asking about available subdomains for a domain id, filtering by name with pagination. Lacks explicit when-not-to-use or alternatives, but guidance is clear and contextually complete.
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!