Lawstronaut

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.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a return-shape statement ('Content full text list with document_id, full_text') and jurisdiction scope, but does not discuss pagination defaults, auth, or other operational behavior.

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

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

The description is front-loaded with purpose and uses clear sections ('Use this tool when', 'Parameters', 'Returns'). However, the Parameters section is a partial duplicate of the schema and is inconsistent with the use-case bullets, which mention filters like status, repealed, and publication_date that are absent from the Parameters 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?

For a read-only retrieval tool with rich annotations and a fully described schema, the description is largely sufficient: it provides the required parameter, return shape, and common use cases. It does not route to siblings like get_document_with_version or get_markdown, but the schema and annotations cover the remaining calling details.

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 explains all 26 parameters. The description repeats a small subset of parameters without adding meaningful detail such as default limit/offset behavior or date formats, so it adds little 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 first sentence uses a specific verb ('Retrieves') and resource ('full text') and scopes it to a jurisdiction with optional filters. This is enough to set it apart from list/get siblings, though it never names a contrasting tool.

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' bullets state concrete query intents such as available full text for portal, title, URL, status, or filtering by authority/source/tag. This gives clear context but no when-not-to-use guidance or alternative tool names, so it stops short of full routing.

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

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

Annotations already 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.

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so safety coverage is handled by annotations. The description adds a useful return contract ('Content markdown list with document_id, content_markdown'), but it does not disclose pagination behavior or how multiple filters interact.

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 tool purpose is front-loaded and the use-case bullets make the structure readable. However, the Parameters section duplicates schema information, is incomplete, and the description includes both usage filters and a parameter list that overlap without being aligned.

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 26-parameter retrieval tool with no output schema, the description provides the required iso field and a basic return shape, which is helpful. Yet it omits many available filters from its parameter list, does not describe pagination or default behavior, and offers no detail on how filters combine, leaving notable gaps for a tool this complex.

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 every parameter; the description mostly repeats labels rather than adding deeper meaning. Its Parameters section is also incomplete relative to the 26-property schema, leaving some filterable fields like status, tag, and repealed out of the listed parameter names.

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 a specific verb and resource: retrieving markdown for a jurisdiction, with optional filters, and it is more than a restatement of the tool name. However, it does not explicitly differentiate from siblings like get_document_text or get_document_with_version.

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 says when to use the tool via 'Use this tool when...' bullets, listing several filter categories such as title, status, repealed, issuing_authority, and tag. It lacks when-not guidance or alternative tool routing, so it stops 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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that it 'only returns content that has crawled data', which is not in annotations. It does not contradict annotations and provides additional context about output restrictions.

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 and front-loaded purpose. It lists parameters and return fields efficiently, though it repeats schema parameter descriptions, adding some redundancy. The length is justified by the tool's complexity (26 params, no output 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?

For a complex tool with no output schema, the description provides a comprehensive return-field list and the crawled-data restriction, which are essential. It also gives usage conditions. It lacks details like default limit/offset values, ordering, or interaction between filters, but these are not critical for correct invocation. The description is sufficient for an agent to call the tool appropriately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 26 parameters are already documented in the schema. The description repeats these parameter meanings without adding new semantics like date formats, value constraints, or default behaviors. It does list return fields (valuable since no output schema exists), but that is output semantics, not parameter semantics. 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 states a clear verb ('List'), resource ('documents'), and scope ('in a jurisdiction with structured filters and pagination'). It distinguishes itself from sibling list_* tools (which list authorities, categories, etc.) and get_* tools (which retrieve specific documents) by focusing on document listing with filters.

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 explicit conditions covering user intents and filter scenarios, making when-to-use clear. It lacks an explicit 'when not to use' or named alternatives, but the conditions are specific enough to guide selection without ambiguity.

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

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

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.

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.

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.

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.

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.

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.

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.