reference-data-mcp-server

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

The description goes well beyond the readOnlyHint annotation by specifying the exact return contents (CODATA 2022 value, SI unit expression, relative standard uncertainty, short description) and the fuzzy-matching fallback behavior. It also confirms that both common names and symbols resolve correctly, which is useful behavioral information.

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

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

Three sentences front-load the core purpose, then state outputs, then give useful examples and the fuzzy fallback. Every sentence adds information; there is 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?

For a single-parameter read-only lookup tool with an output schema, the description covers the query format, acceptable inputs, return contents, and edge-case behavior. Nothing essential is missing for an agent to select and 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 description coverage is 100% and the schema already documents the query parameter with examples. The description adds value by explaining alias recognition and fuzzy matching, giving the agent a more accurate model of what query strings will work.

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 names a specific verb ('look up'), resource ('fundamental physical constant'), and query forms ('name, symbol, or common alias'). It is clearly distinguishable from sibling tools like ref_element_lookup and ref_geo_lookup because the domain is explicit and illustrated with concrete constant examples.

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 makes the use case clear: any time an agent needs a fundamental physical constant and its CODATA 2022 value or uncertainty. It does not explicitly say when to prefer a sibling tool, but the domain distinction is strong enough that the agent can infer the correct 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`, so the description does not need to restate non-mutation. It adds useful behavioral detail beyond annotations: unavailable properties for synthetic/insufficiently studied elements are explicitly returned as null. No contradiction with annotations exists.

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 the core lookup behavior and then lists the returned record efficiently. The enumeration of fields is long but earns its place by specifying units and null behavior; minor restructuring could improve readability.

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

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

With an output schema present and read-only annotations, the description is nearly complete: it states accepted inputs, enumerates returned fields, and clarifies null semantics. It does not explicitly describe failure/not-found behavior or when to use a sibling search tool, which keeps it from being fully 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 input schema already explains `query` and `by` well. The tool description reinforces the query forms but does not add new parameter-level semantics beyond what the schema provides.

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 identifies the verb ('Look up'), the resource ('periodic table element'), and the three accepted input forms. It is clear enough to distinguish from the 'search' siblings, but it does not explicitly name or contrast with `ref_element_search`, so it stops short of a 5.

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 tool's use case is implied by describing exact lookups by name, symbol, or atomic number, and by enumerating the returned fields. However, there is no explicit guidance about when to choose this lookup tool over `ref_element_search` or the other reference lookup siblings, nor any stated exclusions.

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 mark the tool as read-only, and the description adds useful behavioral context: it returns a summary list and requires at least one filter. This exceeds what the schema alone conveys without contradicting the annotations.

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

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

The description is front-loaded with the action and filter options, then gives requirements, output shape, and sibling routing. The category list is useful but partially redundant with the schema's own list, keeping it just shy of top score.

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?

Covers what the tool returns, when it must be used, and which sibling to use for full records; the output schema handles return details. It does not specify multi-filter combination semantics, but that is not clearly necessary for this 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%, so the baseline is 3. The description adds the crucial constraint that at least one filter must be supplied even though the schema lists zero required parameters, and it enumerates valid category values.

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 ('Filter') and resource ('periodic table elements'), and enumerates the exact filter dimensions. It also distinguishes itself from ref_element_lookup by stating that lookup provides the full record for a specific element.

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 that at least one filter is required, which defines when the tool is applicable. It also routes users to ref_element_lookup for full records, giving clear guidance on which sibling to choose.

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 readOnlyHint=true already signaling a safe read operation, the description adds useful behavioral context by revealing fuzzy name matching with the concrete example that 'Brasil' and 'Brazil' both resolve. It also summarizes the returned record fields. It does not contradict the annotations, though it does not discuss error or unknown-query 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?

Two sentences carry all the essential information with no filler. The primary lookup modes are front-loaded, the return contents are summarized efficiently, and the fuzzy matching example adds value without bloating the description.

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-only lookup tool with a full input schema, output schema, and readOnlyHint annotation, the description is largely complete: it covers accepted inputs, result contents, and a notable matching behavior. The main gap is the lack of guidance around ambiguous or unknown queries and no sibling differentiation, but those are minor for this tool's 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%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining fuzzy matching behavior and giving concrete input examples for the query parameter. The 'by' parameter is left to the schema, which is acceptable given the schema already documents the auto/name/alpha2/alpha3 strategy.

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: look up a country by name, ISO alpha-2, or alpha-3 code, and returns a full country record. It is understandable on its own, but it does not explicitly distinguish itself from the sibling ref_geo_search, so it stops short of full sibling differentiation.

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 when to use the tool: when you have a country identifier and want the full country record, including fuzzy name matches. However, it gives no explicit guidance about when not to use it or what distinguishes it from ref_geo_search and other lookup tools, so usage context remains implicit rather than 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral context: at least one filter must be supplied, results are ranked, and returns are summaries rather than full records. It does not explain the ranking criteria, but this 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 three sentences with no redundant phrasing. The essential constraint 'At least one filter is required' appears early, and the pointer to ref_geo_lookup is concise and useful.

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 an output schema, so return values need not be described in detail; the description still notes that results are summaries and ranked. The 'at least one filter' constraint and lookup pointer cover the main usage context. A slight gap is the unspecified meaning of 'ranked,' but overall the description is complete enough for 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 description coverage is 100%, so all six parameters are already well documented. The description enumerates the filter dimensions but adds no new meaning beyond the schema's parameter descriptions. 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 searches and filters countries by multiple dimensions and returns a ranked list of summaries. It explicitly contrasts itself with ref_geo_lookup, which fetches the full record, making the tool's distinct purpose obvious.

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 states that at least one filter is required, indicating when the tool is appropriate, and explicitly directs users to ref_geo_lookup for full records. This provides clear routing between 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 declare readOnlyHint=true, indicating a non-destructive read operation. The description adds detail about the return fields (reason phrase, description, category, cacheability, RFC) and behavior for keyword queries (returns closest match plus alternatives). This goes beyond the basic annotation but doesn't describe potential edge cases such as invalid queries or ambiguous matches. Given the annotation covers safety, a 3 is appropriate.

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, covering purpose, return fields, behavior, and keyword handling in three sentences with no redundancy. It is front-loaded with the core purpose first, then elaboration.

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 an output schema which likely describes the return structure, so the description doesn't need to explain return values. The description covers query types and return fields, which is sufficient for an agent to call it correctly. It doesn't cover error cases (e.g., unknown code), but the output schema may handle that. Overall, nearly 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%, with the query parameter fully described in the schema ('Numeric status code... or descriptive keyword...'). The description adds examples of keywords and clarifies the output, but does not add significant new information beyond the schema. Baseline 3 is appropriate since the schema already handles parameter documentation.

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: looking up HTTP status codes by number or keyword. It specifically lists the resource (HTTP status codes) and the verb (look up), and details what is returned. It is easily distinguishable from siblings which cover constants, elements, geo, timezone, etc.

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

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

The description explains when to use this tool: when the user wants information about an HTTP status code by number or keyword. It does not explicitly mention that for other reference lookups (e.g., constants, elements) the user should use sibling tools, but this is implicit from the sibling names and the scope. No exclusions are stated, 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?

Annotations already declare readOnlyHint=true, so the description carries less safety burden, but it adds valuable behavioral detail: it returns the canonical MIME type, known extensions, compressibility flag, and data source. It also discloses how ambiguity is resolved (canonical first, alternatives listed), which is exactly the kind of behavior an agent needs to interpret results correctly. No contradiction with annotations.

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

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

The description is three sentences with no filler. The core purpose and accepted inputs lead, followed by output details and ambiguity handling. Every sentence earns its place and the length is appropriate 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?

With a fully described parameter, an output schema, and read-only annotations, the description covers all essential aspects: input forms, output contents, behavior on ambiguous extensions, and a use-case hint (Content-Encoding). It leaves no critical gap that would prevent an agent from calling the tool correctly or interpreting its 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 describes the query parameter with examples and 100% coverage, so the baseline is 3. The description adds extra meaning beyond the schema by reinforcing accepted forms ('image/webp', '.webp', 'webp') and providing a concrete resolution example ('.jpg' → 'image/jpeg'), which helps the agent predict output for edge-case extensions. This modest addition justifies a 4.

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 and resource: 'Look up a MIME type by type string or file extension.' It clearly distinguishes itself from sibling lookup tools (constants, elements, geo, HTTP status, timezone, unit) by naming the exact resource type. It also states the accepted input forms, leaving no ambiguity about what the tool does.

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

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

The description gives clear usage context: it explains accepted query formats, the behavior for extension lookups ('.jpg' resolves to 'image/jpeg'), and notes compressibility is relevant for Content-Encoding decisions. It does not explicitly name when not to use the tool versus siblings, but the sibling names make the alternative choice obvious, so the absence of exclusions is not a serious gap.

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 provide readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: it explains that the input is interpreted as local time in the source timezone, that the output shows both UTC offsets to make DST transitions visible, and that it accepts IANA IDs or city names. This exceeds the minimal disclosure required and 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 three sentences, front-loaded with the core verb and purpose. It efficiently conveys input format, output behavior, and accepted timezone formats without redundancy. It could be slightly tightened, but every sentence carries meaningful information and there is 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?

The tool has an output schema (indicated by context signals), so return values are already covered. The description fully explains the input contract (local datetime, source/target timezones), the interpretation rule (local time without offset), and the output behavior (equivalent local time with UTC offsets for DST visibility). No critical information needed for correct invocation is missing.

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 description coverage is 100%, so all three parameters (datetime, from_tz, to_tz) are already documented with descriptions. The description reinforces the datetime format (no offset) but does not add substantive meaning beyond the schema. It mentions accepted formats for timezones (IANA IDs or city names), which is also present in the schema. Thus, baseline 3 is appropriate; the description adds no critical param semantics beyond what the schema provides.

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 specific verb ('Convert'), a precise resource (local datetime from one timezone to another), and explicitly defines input/output semantics. It distinguishes itself from the sibling ref_timezone_lookup (which implies lookup, not conversion) by describing the conversion action and output format.

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

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

The description clearly conveys when to use the tool (converting local datetimes between timezones) and provides usage context (input is local time without offset, output shows both UTC offsets). It does not explicitly mention when not to use it or name the lookup sibling as an alternative, but the conversion purpose is unambiguous enough to imply selection over a lookup tool.

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, so safety is covered. The description adds valuable behavioral detail beyond structured data: partial matching behavior with concrete examples ('Tokyo' resolves to 'Asia/Tokyo', 'NY' resolves to 'America/New_York') and the country-mode behavior of returning all timezones observed in that country.

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 focused sentences with no filler. The core purpose is front-loaded, followed by output details and then behavior examples, so the most important information appears first and 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?

The description covers query modes, return fields, country behavior, and partial matching, while the output schema handles return shape details. For a read-only lookup tool, nothing essential is missing for an agent to invoke it 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 description coverage is 100%, so baseline is 3. The description adds semantic value beyond the schema by illustrating partial-match resolution and clarifying that country mode returns multiple timezones, which helps the agent anticipate return variety.

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 plus resource: 'Get timezone info by IANA ID, country code, or partial city/region name.' It clearly differentiates this from siblings like ref_timezone_convert by specifying lookup-oriented outputs such as UTC offset, DST status, and major cities.

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 clear context on when to use it: any timezone info lookup by ID, country, or partial name. It also explains mode behavior ('auto tries all strategies') and country-query semantics. It does not explicitly name alternatives or exclusion cases, but the context is specific enough for an agent to apply correctly.

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 readOnlyHint annotation already communicates safety, and the description adds meaningful behavioral context: non-linear temperature conversions are handled, unit aliases like 'mt' and 't' are defined with their base values, and mismatched quantities produce an error. Precision or rounding behavior is absent, but the output schema mitigates that 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 front-loaded with the core action and then gives a dense but necessary inventory of supported units. Every sentence earns its place: the first states the purpose, the second lists admissible units, and the third explains failure behavior. The long unit lists could be more scannable with line breaks, but there is no wasted prose.

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 conversion tool with three simple parameters, a read-only annotation, and an output schema, the description covers all needed information: supported categories, unit abbreviations, alias definitions, non-linear handling, and the mismatch error case. An agent can select and invoke this tool correctly without further inference.

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 documents value, from, and to with 100% coverage, so the baseline is 3. The description adds value by providing the accepted unit catalog, aliases, and category groupings, which directly informs what values can be passed to from and to.

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?

States a specific verb and resource: 'Convert a numeric value between compatible units of measure.' It enumerates 11 supported quantity types and their unit abbreviations, making it easy to distinguish from sibling reference-lookup tools. The physical-unit scope also separates it from timezone_convert without 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?

Clearly scopes usage to compatible units and explicitly states that incompatible units return an error identifying the quantity mismatch. It does not explicitly name alternative tools or say when not to use it, but the detailed categorization of physical units makes the boundary reasonably clear.

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