referencesource.org

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

With no annotations provided, the description carries the full burden. It states the tool 'fetches one record,' which implies a read-only operation, and adds useful context about where to find record ids. However, it does not disclose error behavior, whether the record may be null/not found, or any access restrictions. This is sufficient for a simple get but could be more 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 at two sentences, front-loaded with the main action ('Fetch one record by its id'), and each sentence adds value: the first defines the operation, the second provides essential context for locating the record id. No waste.

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?

There is no output schema, so the description should clarify the return value. It says 'fetch one record' which implies the record is returned, but it does not specify the format, fields, or behavior in case of missing records. Given the tool's simplicity, it is adequate but has clear gaps in completeness.

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

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

The input schema already has high coverage (100%) for the two parameters, but the description adds meaning beyond the schema by explaining that 'record ids appear in search_records results and in each record's url,' helping the agent understand how to obtain the record_id value. This extra guidance raises it above the baseline 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 'Fetch one record by its id from a dataset.' It uses a specific verb ('fetch'), identifies the resource (one record by id), and distinguishes from siblings like search_records (which searches) and list_datasets (which lists datasets).

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 context on when to use this tool: 'Record ids appear in search_records results and in each record's url.' This implies usage when you already have a specific record id, and differentiates from search_records which would be used to discover ids. It lacks an explicit '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 provided, the description carries the full burden. It mentions the scope ('every published dataset') and what fields are returned, but does not explicitly state whether this is a read-only operation, whether authentication is needed, or how the list is delivered (e.g., pagination). The verb 'List' implies read-only but without explicit disclosure, the transparency is only partially addressed.

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 single, information-dense sentence that front-loads the main purpose, lists the returned fields, and ends with a practical usage hint. Every word earns its place; 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 simple, 0-parameter tool, the description fully covers what it returns (fields listed) and how to use the result (slug with sibling tools). However, it does not mention any limitations like response size, sorting, or whether the list is exactly what it seems. A bit more context about the nature of 'URLs' or if there are any constraints would push it to a 5.

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

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

The tool has zero parameters, so the description cannot add parameter-level meaning. Per the scoring rubric, a baseline of 4 is appropriate when there are no parameters. The description does not need to explain parameters that do not exist.

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: 'List every published dataset on referencesource.org' with a specific list of fields. It also distinguishes itself from siblings by instructing to use the slug with search_records or get_record, which are record-focused tools.

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

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

The description gives clear context for use, indicating it lists datasets and that the returned slug can be used with sibling tools. However, it doesn't explicitly state when NOT to use this tool or provide direct replacements for alternative scenarios, 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 the full burden. It discloses key behaviors: case-insensitive matching, searching across all field values, a 20-record limit, and the inclusion of 'url, source and verbatim source_quote.' It does not describe error handling or explicitly confirm read-only behavior, but the search function and return of records strongly imply a safe read operation. This adds meaningful behavioral detail beyond the schema.

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, front-loaded with the action, and every clause adds value. It states the operation, the matching behavior, the result limit, and the return fields without redundancy. This is appropriately sized 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?

Given there is no output schema, the description compensates by explaining what the response contains (up to 20 records with url, source, and source_quote). It also covers the search semantics. It does not mention empty-result behavior or exact JSON shape, but for a simple two-parameter search tool, this is sufficiently complete. A minor gap is not specifying what happens with no matches, but this is not critical.

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 (query and dataset_slug) having clear descriptions. The description does not add significant meaning beyond the schema—it reiterates 'one dataset's records' for dataset_slug and 'case-insensitive substring' for query, but the schema already provides examples and source. This is the baseline score for good schema coverage with no extra parameter detail.

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

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

The description clearly states the tool's function: 'Search one dataset's records for a case-insensitive substring across all field values.' It uses a specific verb ('search'), identifies the resource ('one dataset's records'), and adds scope ('case-insensitive substring across all field values'). This distinguishes it from siblings like get_record (which retrieves a specific record) and list_datasets (which lists datasets).

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 context (searching within a dataset when you have a dataset_slug and query) but does not explicitly mention alternatives or when not to use it. It notes that results include 'verbatim source_quote for verification,' which hints at a verification use case, but there are no direct comparisons to sibling tools. This is implied guidance, not 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 transparency burden—and it succeeds. It discloses the matching modes (exact, case-insensitive, normalized), the check against source_quote, the returned artifacts (url, source, source_quote), and the complete verdict set. It even clarifies that the attestation is about the source's content, not objective truth, which is a valuable behavioral nuance.

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 purpose and followed by behavioral details. Each sentence earns its place, but the middle sentence is somewhat dense and could be split for easier parsing. Still, there is no filler or redundancy, and the structure flows logically.

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

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

Given the absence of an output schema and annotations, the description does a strong job of conveying the expected response: it names verdicts, return fields, and matching behavior. It does not detail the exact JSON structure or error cases, but for a verification tool this is sufficient. The description is complete enough for an agent to invoke the tool correctly and interpret 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 schema already documents all four parameters with clear examples, so the baseline is 3. The description adds meaning by explaining what happens when field is omitted ('every stored field is checked') and when record_id is omitted ('the dataset's stored values are searched'), as well as noting that the match type is named in the verdict. This provides functional context beyond the schema.

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

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

The description opens with a specific verb and resource ('Check a claimed value against a published record') and immediately distinguishes this tool from siblings like search_records and get_record by focusing on verification rather than discovery. It also enumerates concrete verdicts (matches_record, matches_quote, differs, not_found), making the tool's role unmistakable.

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 frames when to use this tool: to verify a claim against a published record instead of taking it at face value. It also notes the epistemic limitation ('never whether the claim is true in the world'), which helps agents avoid misapplying the result. However, it does not explicitly name alternative tools or provide when-not-to-use scenarios, so it falls just short of the highest bar.

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