Marks & Signatures

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

The annotations already establish read-only, idempotent, closed-world, and non-destructive behavior. The description adds useful behavioral context beyond that by noting that results are paged and that each maker includes place, active years, mark count, and an example mark image.

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 front-load the search purpose and follow with the return format. Every sentence earns its place, with no redundant or vague wording.

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 a rich schema, full annotation coverage, and an output schema, and the description adequately covers purpose and result shape. It could be slightly more complete by clarifying how this discovery tool relates to the sibling detail and mark tools, but nothing essential for calling it correctly 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?

Schema coverage is 100%, so all five parameters are already documented in detail, including the empty-query browse behavior and pagination semantics. The description only restates that category and country are optional filters, adding no extra syntax or meaning 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 states a specific verb ("Searches") and resource ("makers and their aliases") and scopes it across named categories. It does not explicitly distinguish this discovery tool from siblings like get_details or get_maker_marks, 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 description implies usage when searching for a maker by name and notes optional category or country filtering, but it gives no explicit when-to-use or when-not guidance relative to get_details, get_maker_marks, or identify_mark.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no restating. The description adds the shape of the payload (wording/type/period/dating notes vs history/aliases/look-alikes, plus page links), but much of that overlaps with the existing output schema rather than adding genuinely new behavioral 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?

A single front-loaded sentence with the resource and scope stated first, followed by a compact semicolon-delimited field list and a trailing note about links. Dense but no filler sentences; the field enumeration is the only slightly heavy part.

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 one-parameter read tool with a rich annotation set and an output schema, the description covers purpose, both entity types, and return contents. What remains missing is explicit routing against the sibling tools, which is the main thing an agent could still get wrong.

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 id parameter is fully documented there, including the "mark:..." / "maker:category/slug" formats. The description's only addition is confirming the id may refer to either a mark or a maker, which is marginal beyond the schema; baseline 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?

States a concrete verb and resource ("Returns the full public record for one mark or one maker") and enumerates the record contents, so the agent knows exactly what it gets. The "one mark or one maker" scope implicitly separates it from the plural siblings (find_makers, get_maker_marks), but no sibling is named outright.

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?

Usage is only implied: the phrase "from earlier results" in the schema hints this is a follow-up drill-down after a search, and the singular scope implies it is not a list tool. There is no explicit statement of when to prefer this over get_maker_marks or identify_mark, and no 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 declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds meaningful behavioral detail beyond that: it lists returned fields and specifies date ordering, including the special ordering when a mark id is supplied.

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 tight sentences with no filler. The core purpose is front-loaded, followed by the input and ordering behavior.

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 one-parameter read tool with annotations and an output schema, the description covers purpose, accepted id types, and ordering. The main remaining gap is explicit routing guidance against sibling tools.

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

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

Schema description coverage is 100%, and the schema already documents the single id parameter as an exact mark or maker id from earlier results. The description reinforces the dual id types and adds ordering behavior, but it does not add syntax or format details 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 states a specific verb and resource: it returns the marks of one maker, including images, wording, type, period, and date order. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as find_makers or identify_mark.

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 that the id may be a maker id or a mark id, and that a mark id places that mark first. This gives useful input context, but it does not state when to use this tool instead of find_makers, get_details, or identify_mark, nor does it give 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 establish read-only, idempotent, non-destructive behavior, and the description adds that results are ranked and delivered in pages with matched-detail explanations plus an external search link. It does not discuss rate limits or ordering specifics, but with an output schema and safety annotations the additional context is solid.

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 are front-loaded with the purpose and searchable facets, then the result shape and external link. There is no redundant or filler wording.

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 an 11-parameter optional-argument search tool with a full schema, output schema, and safety annotations, the description covers the core search surface and what users get back. The main omission is explicit sibling routing, which is more of a usage-guideline gap than a completeness failure.

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 schema already documents all 11 parameters, including cursor and pageSize. The description adds a natural-language map of searchable facets such as wording, symbols, border, colour, type, category, country, and years, but does not add syntax or constraints 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 ('Ranks catalogue marks') and enumerates the facets it matches, making the tool's job clear. It does not explicitly contrast itself with siblings such as find_makers or get_maker_marks, so it falls 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 the tool is for identifying a mark from a description, but never states when to choose it over find_makers, get_maker_marks, or get_details. No exclusions or alternative-path guidance is provided.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the result set is fixed at five categories and each entry carries mark counts, maker counts and a category page link. It stops short of stating ordering or whether counts are live, but nothing contradicts 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?

A single front-loaded sentence that states the resource, the cardinality and the returned fields with no filler. Every clause carries information an agent would otherwise have to discover by calling the 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?

With an output schema present, the description needn't document return structure, and it goes further by summarizing what each category entry contains. For a zero-parameter, read-only browse tool this is sufficient to call 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 tool takes no parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly signals a parameterless, unfiltered listing rather than implying hidden filtering options.

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 pairs a specific verb ('Lists') with a specific resource ('the five mark categories') and states the payload (mark/maker counts plus a link per category). It implicitly separates itself from siblings like find_makers and get_maker_marks by naming categories rather than makers or marks, though it never names a sibling explicitly.

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?

There is no when-to-use guidance, no mention of it being the entry point before calling get_details, and no exclusion of alternatives. An agent must infer from the sibling names alone that this is the browsing/starting call.

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