OpenDataModels MCP server

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

With no annotations provided, the description carries the full burden. It explains what the tool produces (flat delimited string), the list of available meta-fields, and includes a concrete example. It does not discuss error behavior, permissions, or edge cases, but for a read/export operation this is reasonable.

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

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

The description is concise and well-structured: it opens with the core purpose, then provides usage context, then lists available meta-fields, and ends with a representative example. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 parameters and no output schema, the description is quite complete. It explains the output format, the selectable fields, and demonstrates invocation. Minor gaps remain about row separation or exact output format details, but the example clarifies most usage.

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

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

Schema coverage is 100% and the schema already describes each parameter. The description adds value by listing all valid meta-field values and providing a worked example, which reinforces the semantics of 'fields' and 'separator' beyond the schema's default list.

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 exports attributes of a data model as a flat delimited string with caller-selected meta-fields. This specific verb+resource+output format distinguishes it from siblings like get_attributes_for_model or get_attribute_details.

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 'Use this when a data engineer needs a CSV-ready or pipe-delimited listing' and gives concrete use cases (database column mapping, ontology alignment, spreadsheet import). It does not explicitly mention alternatives or when not to use it, but the context is clear enough.

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?

No annotations are provided, so the description carries the burden. It reveals that the result is always prefixed with 'dataModel.' and gives an example call, which is useful. However, it does not mention behavior when the model name is not found, whether it returns a single value or array, or any side effects. For a simple lookup, this is acceptable but not fully transparent.

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

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

The description is concise and well-structured: it states the purpose, gives a usage scenario, and provides an example call in two sentences. Every sentence adds value, and the example is directly useful for invocation. It is appropriately sized for a simple one-parameter tool.

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 simple lookup tool with one parameter and no output schema, the description is nearly complete: it explains what the tool does, when to use it, how to call it, and the prefix on the result. The only gap is the lack of explicit error behavior or return type specification, but given the tool's simplicity, this is a minor omission.

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% for the single parameter model_name, and the schema already explains what it is. The description adds an example invocation and clarifies the source context (NGSI-LD payload), but this is marginal. The parameter semantics are largely defined by the schema, so a 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 the tool's function: 'Find which SDM subject (repository group, always prefixed with 'dataModel.') a data model belongs to'. It uses a specific verb ('Find') and resource ('SDM subject'), and includes a concrete example that distinguishes it from sibling tools like get_data_model, as it resolves the subject before that call.

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 explicit when-to-use guidance: 'Use this when you have an entity type from an incoming NGSI-LD payload but don't know its subject'. It also references dependent calls (get_data_model, validate_data), implying when not to use it and providing context. It lacks an explicit list of alternatives but sufficiently oriented the agent.

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?

No annotations are provided, so the description carries the full burden. It discloses the return behavior ('Returns ranked candidates with similarity scores') and the fuzzy-matching behavior, which is useful context. However, it does not mention what happens when no candidates meet the threshold, which is a minor gap.

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 three sentences: purpose, usage guidance, and return info plus example. It is front-loaded and every sentence contributes value. The example is helpful without being verbose.

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 low complexity (two parameters, no output schema), the description covers the core aspects: what it does, when to use it, and what it returns. It lacks details about edge cases (e.g., empty results), but the provided information is sufficient for a simple search tool.

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

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

Schema coverage is 100% with both parameters documented. The description adds an example call but does not provide additional semantic details beyond the schema. The baseline of 3 applies, as the schema already explains the parameters well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Search for a data model by approximate or misspelled name using fuzzy matching.' It specifies the verb (search), resource (data model), and method (fuzzy matching), and distinguishes it from siblings by positioning it as the recovery step when get_data_model fails.

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 usage guidance is provided: 'Use this as the recovery step whenever get_data_model returns MODEL_NOT_FOUND.' This directly states when to use the tool, and the mention of 'finds the closest real model names' implies the alternative fallback use case.

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?

With no annotations, the description carries the burden of behavioral disclosure. It clearly enumerates the returned information (description, NGSI type, data type, units, constraints, model URL), indicating a read-only lookup. No side effects or error conditions are mentioned, but for a simple retrieval tool this is adequate.

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 two sentences plus an example, with no fluff. It front-loads the purpose, then lists the exact fields returned, and includes a concrete usage example. Every sentence earns its place.

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 simple read tool with two fully documented parameters, no output schema, and no nested objects, the description is complete. It covers what the tool does, what it returns, and when to use it. The provided example further anchors the usage context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds an example call with concrete values, but the parameter meanings are already fully documented in the schema. The example is helpful but does not fundamentally expand on the schema definitions.

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 fetches full details for a single attribute within a Smart Data Model, using a specific verb ('Get') and resource. It differentiates from siblings like get_attributes_for_model, which lists attributes, by focusing on a single attribute's detailed fields (description, NGSI type, data type, units, constraints, model URL).

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 usage guidance: 'Use this when the user asks what type a specific field is, what units it uses, or how to populate it.' It lacks explicit when-not-to-use or named alternatives, but the context and example make the intended scenario 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?

With no annotations, the description carries the burden of behavioral disclosure. It transparently lists the exact output contents (NGSI type, data type, etc.) and gives an example invocation. The verb 'List' implies a read-only operation, adding clarity. It doesn't discuss errors or pagination, but for a single-parameter listing tool this is sufficient.

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

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

The description is concise and well-structured: first sentence states the action and output, second provides usage context, third gives a concrete example. Every sentence earns its place with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one parameter, no output schema, and no annotations, the description is nearly complete. It explains the return content in detail and when to use the tool. It doesn't cover error cases (e.g., model not found), but that's a minor gap for a simple lookup tool. The inclusion of an example rounds out the context.

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

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

Input schema has 100% coverage with a clear description of 'model_name' (exact name, examples). The tool description reinforces this with an example: get_attributes_for_model({"model_name": "WeatherObserved"}). This adds practical guidance beyond the schema's placeholder examples, earning a point above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'List all attributes (properties) of a specific Smart Data Model' and details the scope (NGSI type, data type, description, units, reference URL). This distinguishes it from siblings like 'get_attribute_details' (single attribute) and 'get_data_model' (model itself).

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 'Use this after get_data_model when the user wants to understand what fields a model has...' providing clear context and sequencing. It doesn't mention when not to use it or alternatives, but the usage guidance is strong enough for an agent to choose this tool appropriately.

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?

With no annotations, the description carries full responsibility for behavioral disclosure. It clearly indicates a non-mutating retrieval operation and specifies the output content (JSON Schema, metadata, required fields, documentation URL). It does not discuss error handling or caching, but no risky behavior is hidden.

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 two sentences plus a compact example. It is front-loaded with the primary purpose and avoids repeating schema information, making it efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with two well-documented parameters and no output schema, the description covers the purpose, clear usage context, and an example. The sibling list provides additional context for alternatives, making the description 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?

The input schema provides 100% description coverage for both parameters, so the schema already conveys the semantics. The description adds a practical example but does not introduce additional parameter details beyond what the schema documents.

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 ('Retrieve') and resource ('complete JSON Schema and metadata for a specific Smart Data Model'), distinguishing it from sibling search tools by emphasizing a known model name. It also provides an example, making its purpose unambiguous.

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

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

The description explicitly states when to use this tool ('when the user already knows the model name') and what it returns. It also directs users to 'search_data_models first if unsure' in the input schema, giving clear alternative 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?

With no annotations, the description carries the full transparency burden. It discloses key behavioral aspects: returns comprehensive data, includes specific fields, and requires a domain filter to prevent returning the entire catalog. The example call illustrates usage. It does not mention pagination, output format, or read-only nature explicitly, but 'Return' implies read-only and the warning about scope is a strong transparency plus.

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 three sentences, front-loaded with the purpose, then usage, then a constraint and example. Every sentence adds value without redundancy. It is appropriately sized for a tool with one parameter and no complex nested structures.

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 simplicity of the tool (one parameter, no output schema, no annotations), the description covers purpose, usage context, a scope warning, and an example. It misses only minor details like a note about the response being potentially large, but the emphasis on bulk processing already implies that. Overall it is complete enough for an agent to invoke 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?

The schema already fully documents the single parameter with an enum and description, so the baseline is 3. The description adds meaning by explaining why the domain is mandatory ('to prevent returning the entire catalog in one call') and showing a concrete example value. This goes beyond mere schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the complete list of all data models within a specific domain, naming exact output content (names, subjects, descriptions, repository links). It distinguishes itself from sibling tools like get_data_model or search_data_models by focusing on the full-domain, bulk-oriented listing. The verb 'Return' plus specific resource makes the purpose unambiguous.

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

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

The description explicitly says 'Use this when the user needs a comprehensive structured overview of an entire domain for bulk processing, analysis, or selection,' which gives concrete usage context. It does not explicitly mention when not to use it or point to alternatives, but the context is clear enough for an AI agent to differentiate from more targeted tools. The mandatory domain filter is also stated as a usage constraint.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple return statement by explaining the consequence of omitting the @context (invalid linked data, rejection by brokers). It does not explicitly state it's read-only, but 'Return' implies a non-mutating operation. This adds useful context beyond the bare functionality.

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 three sentences: the first states the operation, the second explains its importance, and the third provides a clear example. Every sentence earns its place, and the example is practical without unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one parameter, no output schema, and no annotations, the description sufficiently explains the tool's purpose, usage context, and return value. It could mention error handling for invalid model names, but that is not critical for such a straightforward lookup operation.

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 the parameter 'model_name' already described with examples. The description reinforces this with a usage example but does not add significant new meaning 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 the tool's function with a specific verb and resource: 'Return the NGSI-LD @context URL and context content for a specific data model.' This distinguishes it from sibling tools like get_data_model and get_attribute_details, which focus on other aspects of data models.

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

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

The description provides explicit usage context: 'required when building valid NGSI-LD linked-data payloads' and 'Use this before constructing or validating a normalized payload.' It also includes a concrete example, but does not explicitly mention when not to use it or name alternative tools, though the sibling list makes alternatives 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns URL(s) but does not specify whether the output is a string, array, or object, nor what happens if the model name is not found. The phrase 'URL(s)' hints at potential plurality but lacks detail on error behavior or return structure.

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

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

The description is a concise two-sentence structure with the main action front-loaded, followed by a usage scenario and an illustrative example. Every sentence earns its place with no redundant phrasing.

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 (one parameter, no output schema), the description adequately covers its purpose and typical use case. However, it falls short of full completeness by not describing the return format or potential error conditions, which would help an agent understand expected results.

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

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

The input schema already provides 100% coverage for the model_name parameter with a clear description and examples. The tool description's example repeats this usage without adding new semantic information beyond what the schema already states. Baseline 3 applies because schema coverage is high.

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: 'Return the GitHub repository URL(s) for a specific data model by name.' It names the resource (GitHub repo URL) and the scope (specific data model), distinguishing it from siblings like get_subject_repo_url by focusing on data model names. The example reinforces the purpose.

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

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

The description provides explicit context for when to use the tool: 'Use this when the user needs a direct link to the schema source, examples, or documentation on GitHub.' It does not explicitly name alternatives or state when not to use it, but the use case is clear enough to direct an agent.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the core behavior (finding semantically related models) and provides an example, but it does not disclose details like what the response format will be, whether results are ordered, or how relationship types are determined beyond the schema. It is minimally adequate but lacks richer context.

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 two sentences plus a compact example. It is front-loaded with the main purpose, and every word contributes to understanding. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only two parameters and no output schema, the description is reasonably complete but still leaves the return value to inference. The example hints that model names are returned, but without an explicit statement of the output shape, the description is not fully complete for an agent that has never invoked the tool.

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

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

The schema already provides 100% coverage with detailed descriptions for both parameters. The description adds a concrete example but no additional semantic meaning beyond what the schema already conveys, so the 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 opens with a specific verb ('Find') and a clear resource ('Smart Data Models that are semantically related to a given model'). It distinguishes itself from sibling search tools by focusing on semantic relationships rather than generic search or attribute lookup, and the concrete example reinforces this unique purpose.

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

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

It explicitly states the use case: 'useful for discovering adjacent models when building multi-entity systems.' This gives clear context for when to invoke the tool, though it does not explicitly mention alternative tools or say when not to use them, which prevents 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It states the return value (GitHub repo URL) and gives an example, but it does not mention potential behaviors like network access, error handling, or validation of subject format. For a simple read-only lookup, this is adequate but not rich.

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 two sentences plus an example, front-loaded with the core purpose. Every sentence earns its place; there is no fluff or repetition.

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 low-complexity tool with one parameter and no output schema, the description is largely complete: it states purpose, usage, and an example. It could mention the return format (plain URL string) or validation behavior, but these are less critical given the simplicity.

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 a clear parameter description. The description adds a concrete example ('dataModel.Weather') and reinforces the subject format, which helps the agent understand the expected input beyond the schema alone.

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 'Return the GitHub repository URL for an SDM subject' with a specific verb and resource. It does not explicitly differentiate from the sibling tool get_model_repo_url, so it loses a point for lack of sibling distinction.

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

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

The description provides clear when-to-use context: 'Use this when the user wants to browse the source files, open issues, or cite the authoritative schema location for a subject group.' It does not mention any exclusions or alternative tools, but the usage context is explicit.

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?

With no annotations provided, the description carries the full burden. It transparently states that it lists all domains with counts, clarifies there are no parameters, and shows an example invocation. For a read-only list operation, this is sufficient, though it does not mention explicit return format or side effects.

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

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

The description is concise and well-structured: it leads with the core function, then provides usage context, then parameter clarity, and ends with an example. Every sentence adds value without redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless list tool with no output schema, the description is complete: it specifies the output content (domains and counts), when to use it, and how to invoke it. It also references the next logical step, making the surrounding context fully covered.

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?

There are zero parameters, so the schema coverage is 100% trivially. The description reinforces this with 'No parameters required' and a call example, meeting the 0-parameter baseline of 4 and adding practical clarity.

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 'List' and the resource 'SDM domains', adding 'count of data models in each' for specificity. It also distinguishes from the sibling 'list_models_by_domain' by positioning itself as the entry point, making its unique role clear.

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 'Use this as the entry point when the user wants an overview' and 'before calling list_models_by_domain', providing concrete when-to-use guidance and naming the relevant alternative. This meets the 'explicit when/alternatives' criteria.

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?

No annotations are provided, so the description carries the full burden. It adds context about requiring valid domains from list_domains and gives an example, but does not describe pagination, error behavior, or the exact return shape. For a simple read operation, this is adequate but not deeply transparent.

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 three concise sentences with an illustrative example, front-loaded with the primary action and no redundant filler. Every sentence earns its place.

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 simple two-parameter listing tool, the description covers purpose, usage context, prerequisite, and an example. It states the output is model names, which partially compensates for the absence of an output schema. Missing pagination details are already in the schema.

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 schema already provides 100% description coverage for both parameters, including the enum for domain and a default for limit. The description reinforces that domain must exactly match list_domains output but does not add additional semantics beyond what the schema already states.

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' with a clear resource ('data model names') and scope ('within a specific SDM domain'), distinguishing it from siblings like search_data_models. It also provides concrete examples and clarifies that it browses all models in a sector.

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 states when to use ('when the user wants to browse all models in a sector') and instructs to call list_domains first to confirm valid domain names. It does not explicitly name alternatives or when-not-to-use, but 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?

With no annotations, the description carries full behavioral disclosure. It explains the search modes (keyword, domain, partial model name), states that it returns 'a list of matching model names and their subjects', and includes an example call. It does not detail matching semantics (exact vs fuzzy), ordering, or pagination, but for a search tool this is acceptable and transparent enough.

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 only two sentences plus an example, with the primary purpose front-loaded. There is no redundancy or fluff, and the example is instructive without being overly verbose.

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 3 parameters, no annotations, and no output schema, the description covers purpose, usage context, search modes, and return structure. It does not mention the limit parameter (but the schema covers it) or result ordering, but overall the description is sufficient for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%: each parameter (query, domain, limit) already has a description. The description's example adds a concrete usage, but does not introduce new meaning beyond the schema. Since the schema does the heavy lifting, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Search the Smart Data Models (SDM) catalog by keyword, domain name, or partial model name.' It specifies a verb and resource, and the phrase 'discover which data models exist for a topic' clarifies the use case. The example further solidifies understanding and distinguishes it from sibling tools like list_models_by_domain or fuzzy_find_model by listing explicit search modes.

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

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

The description provides a clear usage trigger: 'Use this when the user wants to discover which data models exist for a topic (e.g., "parking", "weather", "energy meter")'. This tells the agent when to select this tool. However, it does not mention alternatives or exclusions, so it falls short of a 5.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool returns a structured result with pass/fail and a list of validation errors, and it gives a usage example. It doesn't explicitly state the operation is side-effect-free, but this is implied by 'validate' and 'check if it conforms.'

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 four sentences covering purpose, usage, return value, and an example. The example is slightly lengthy but adds clarity. There's no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's purpose, when to use it, and its output format. It doesn't describe strict mode's effect in detail, but the schema covers that. Given the moderate complexity and no output schema, the description is sufficiently complete, though it could explicitly mention the non-mutating nature.

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 provides comprehensive descriptions for all three parameters (100% coverage), including the `strict` behavior and accepted data formats. The tool description adds an example but doesn't enrich meaning beyond the schema, so the 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 starts with 'Validate a JSON payload against the schema of a specific Smart Data Model,' clearly stating a specific action and resource. This distinguishes it from sibling tools focused on export, search, or catalog access. The concrete example reinforces the intended use.

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

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

It explicitly says 'Use this when the user has an IoT payload or NGSI-LD entity and wants to check if it conforms to the standard,' providing clear context. It doesn't list alternatives, but none of the sibling tools offer validation functionality, so this guidance is sufficient.

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