CaliberAPI Pistol Optic Fit

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

Annotations already cover read-only, idempotent, closed-world safety, but the description adds substantial context: the three fit verdicts and what each means, the caveat that unknown is not evidence of non-fit, and the presentation rule that adapter fits must never be reported as direct. It also mandates citation via the returned citation line and html_url.

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?

Front-loaded with the core question, then the return shapes, then a clear output-fidelity rule. Dense but every sentence carries information; the reporting rule is slightly verbose but justified by the stakes.

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 must describe return values — and it enumerates direct, adapter, unknown and needs_clarification with their payloads. It also supplies the citation obligation, so an agent has everything needed to answer and report correctly.

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

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

Schema coverage is 100% and documents slug-or-name inputs, so baseline would be 3. The description earns more by mapping the clarification retry to the parameters (returning candidates that the agent then passes back as a slug).

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: answering whether a specific red dot optic fits a specific pistol, from source-cited data. It is clearly distinguishable from sibling list/getter tools like get_footprint and list_pistols_for_optic.

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?

Gives a clear operational rule for the ambiguous-name case (returns needs_clarification with candidates; call again with a candidate slug), which tells the agent how to proceed. It lacks an explicit statement of when to prefer this over get_footprint or the list tools, 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered; the description adds substantive content by disclosing the returned facets — screw/recoil lug counts, compatible optics, pistols cut, adapter plates — and that sources are included. It does not mention behavior on unknown names (error vs empty result), which is the main remaining 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?

A single dense sentence: entity scope first, examples second, returned fields third. No filler and no redundancy with the title.

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 no output schema, the description does the necessary work of enumerating what comes back and noting source attribution. Only not-found/ambiguous-name behavior and any result-count expectations are unaddressed, which is a minor gap for a read-only single-entity lookup.

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 explains slug-or-name form, so the baseline is 3; the description earns an extra point by broadening the accepted-name examples beyond the schema (RMR, ACRO, DPP) which signals that common marketing names, not just slugs, are valid.

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 — 'Describe one optic mounting footprint or plate system' — and immediately enumerates real-world examples (RMR, RMSc, ACRO, DPP, Glock MOS) plus the exact facts returned. An agent can distinguish this entity-lookup from compatibility tools without opening the schema.

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 singular 'one ... footprint' wording implies a single-entity lookup contrasted with the sibling 'search', but the description never names an alternative or states exclusions, e.g. that it is not the tool for 'will this optic fit this pistol' (check_fit). Usage is inferable rather than stated.

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?

Beyond the read-only annotations, the description discloses important behavioral constraints: adapter fits must not be misrepresented as direct, unknown must not become does-not-fit, and results should be cited using the returned citation line and html_url. These are non-obvious output-handling rules that materially affect correct use.

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 list operation and follows with concise but necessary usage and output-handling constraints. Every sentence carries actionable information, with no redundant restatement of schema or annotations.

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 no output schema, the description explains the return structure enough for correct use: direct fits with footprint, adapter fits with plate chain, citation line, and html_url. It also covers the key caveat about absent optics, making it complete for this read-only lookup 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 has 100% description coverage, including the pistol slug/name format and the fit enum, so the description does not need to re-explain them. The description adds output semantics around direct/adapter fits but does not add parameter-specific guidance 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: list optics with cited fits for one pistol, including direct/adapter distinctions. It is clear and actionable, but it does not explicitly name the sibling tools it differs from, such as check_fit or list_pistols_for_optic.

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 gives a concrete usage example ('what red dots fit my pistol') and clarifies that unlisted optics lack cited fit rather than proving non-fit. It does not explicitly say when to use check_fit or list_pistols_for_optic instead, so the alternative-routing guidance is implied rather than complete.

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 this as a safe, read-only, idempotent lookup. The description adds meaningful result semantics beyond them: each result is marked direct (with footprint) or adapter (with plate chain), and it warns not to conflate adapter fits with direct fits or 'unknown' with 'does not fit'.

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 result semantics, then gives precise reporting rules. It is dense but every sentence contributes; minor tightening could improve it without changing meaning.

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 carries the burden of explaining return semantics. It covers the direct/adapter distinction, footprint and plate chain fields, unknown handling, and citation/link requirements, which is sufficient for an agent to use the results 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?

With one required parameter and 100% schema description coverage, the schema already explains that the optic may be a slug or name. The description reinforces the single-optic scope but adds no format or validation detail 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 ('List every pistol') scoped to one optic, and its fit-marking behavior distinguishes it from siblings like list_optics_for_pistol and check_fit. An agent can tell exactly what this tool retrieves without opening the schema.

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 gives a clear use case ('what pistols take this red dot') that maps directly to the tool's scope. It does not explicitly name alternatives such as check_fit or list_optics_for_pistol or state when not to use this tool, so guidance is strong but incomplete.

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/closed-world, so safety is covered. The description adds genuinely useful behavior beyond that: it discloses the shape of the result (slugs, names, page URLs) and its role as a feeder for other tools — important since there is no output 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?

Three short sentences, front-loaded with the resource list, then output shape, then the usage condition. No 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?

With only two params and no output schema, the description compensates by describing return fields and the downstream workflow. Minor gaps remain — no mention of result limits, ordering, or behavior when nothing matches — but nothing critical 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?

Schema coverage is 100% and both parameters are documented with an example, so the schema carries the semantics. The description only loosely reinforces that matching is by name; it adds no detail on the `type` filter or match behavior, so 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 specific verb (find) and the exact resources covered (pistols, optics, footprints) plus the lookup key (name). This clearly separates it from siblings like get_footprint or check_fit, which take exact identifiers rather than fuzzy names.

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?

"Use it when you are unsure of an exact model name" gives a clear triggering condition, and "pass to the other tools" frames it as the discovery step in a workflow. It stops short of naming which sibling to use once an exact name is known, so it isn't fully explicit about alternatives.

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