optical-intelligence

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

Annotations establish read-only/idempotent/non-destructive behavior; the description adds the computational formula, the sign convention for nasal/temporal, and the no-prism limitation. This is useful behavioral context beyond the annotations. There is no contradiction.

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 front-loads the formula and follows with sign convention and exclusions; 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?

For a calculation tool with no output schema, the description covers scope, formula, units, sign convention, and exclusions, which is the core of what an agent needs. It leaves minor gaps such as return shape and language behavior, but these are not critical to correct 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 coverage is 0%, so the description must carry parameter meaning; it does for the main inputs by giving the formula with A, bridge, and monocular PD per eye. It does not explain the optional 'language' parameter, but its enum/default in the schema mitigates this.

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 precise calculation formula with scope ('Symmetric boxing frame only'), sign convention ('Positive nasal'), and exclusion ('No vertical or prescribed prism compensation'), making the tool's function unmistakable and distinguishing it from optical siblings like calculate_prism.

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 clearly defines when the tool applies: symmetric boxing frames only, and explicitly excludes vertical and prescribed prism compensation. It does not name a specific sibling as the alternative, so the when-not guidance is present but the alternative routing is left to 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?

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds genuine value beyond those annotations by stating the calculation formula, the use of absolute value, and that the result is magnitude only with no base direction or prescription recommendation. It stops short of clarifying the mm-to-cm unit conversion, but the core behavioral profile is 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 entire description is a single tight sentence that front-loads the central formula and immediately follows with the return limitation. Every phrase adds either formula context or usage caution; there is 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?

For a simple three-parameter calculator the description covers the formula and the nature of the return value, which is a reasonable baseline. However, without an output schema it leaves the output unit unstated, fails to mention the language parameter, and does not resolve the displacement unit mismatch, so an agent could still invoke or interpret the result incorrectly.

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 0%, so the description carries the full burden for parameters. It references meridionalPower and displacement through the formula and clarifies absolute value, but it omits the language parameter entirely and refers to 'displacement in cm' while the actual property is displacementMm, which is potentially misleading. Ranges, units, and conversions are not explained.

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 operation as a Prentice approximation using absolute meridional power times displacement, and it explains that the return is magnitude only with no base direction or prescription recommendation. It does not use an explicit action verb like 'calculates', but the formula and return scope make the purpose unambiguous. It is distinct enough from the sibling calculation tools, though it does not name a specific sibling.

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 word 'Educational' and the explicit 'no prescription recommendation' imply that this is for learning contexts rather than clinical decision-making. However, there is no positive guidance on when to choose this tool over the siblings, nor any named alternatives or exclusions beyond the recommendation caveat.

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, and destructiveHint=false, so the safety profile is established. The description adds useful behavioral context beyond that: the topic is 'public' (implying no special access), the ID is 'stable' (reinforcing deterministic retrieval), and the result includes references, related topics, and limitations. There is no contradiction with 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 delivers the key action ('Read a public optical topic'), the lookup key ('by stable ID'), and the output highlights ('with references, related topics and limitations'). There is no filler, repetition, or unnecessary detail.

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 tool with strong annotations and a closed enum for the ID, the description covers the core purpose and even hints at the return contents. The main gap is the undocumented 'language' parameter and the absence of any output shape details, though there is no output schema for the agent to fall back on.

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 0%, so the description must compensate for the two parameters, but it does not. It characterizes 'id' only as a 'stable ID' and never mentions the 'language' parameter, its allowed values, or its default of 'pt'. The enum values themselves are self-explanatory, but the language semantics are entirely undocumented in both the schema and the description.

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 ('Read'), the resource ('public optical topic'), and the lookup mechanism ('by stable ID'), and it even previews the return contents ('references, related topics and limitations'). It does not explicitly contrast itself with siblings like search_optical_knowledge or the calculators, so it misses the full 5 for sibling differentiation, but the intent is 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 phrase 'by stable ID' implies this is the right tool when the caller already has a known topic ID, rather than for free-text search or calculations. However, the description does not explicitly state when to prefer this tool over search_optical_knowledge or when a calculator would be more appropriate, leaving the routing largely to inference.

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 cover readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context beyond those: it returns source excerpts and excludes medical advice and customer records. This is good value, though it does not mention rate limits, authentication, or result 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?

Two concise, front-loaded sentences. The first names the verb, resource, and scope; the second adds return-type and exclusion context. 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 simple 3-parameter search tool with strong annotations, the description covers domain, language, return type, and exclusions. The main gap is the lack of result-structure details, but the statement 'Returns source excerpts' gives enough for an agent to reason about 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 0%, so the description carries the parameter-explanation burden. It clarifies the language scope ('Portuguese or English') and the domain, but it does not describe the limit parameter or query semantics beyond what the property names and defaults already imply. Adequate but incomplete.

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 action and resource: 'Search public optical education in Portuguese or English,' and adds output type ('source excerpts'). It is clear and distinct from the calculation-focused siblings, but it does not explicitly differentiate itself from get_optical_topic, so it misses the full sibling-clarity 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 implies when to use the tool: for public optical education content, and provides exclusions ('not medical advice or customer records'). However, it does not explicitly name alternatives or state when to prefer this over get_optical_topic or the calculation 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 already establish read-only, idempotent, non-destructive behavior. The description adds meaningful boundaries beyond that: it operates only on notation, does not alter the actual prescription, and explicitly excludes diagnosis or prescription generation. This is useful context for safe invocation.

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 compact sentences with zero filler. The core operation is front-loaded, and the scope limitations are stated efficiently. 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 pure calculation tool, the description covers the operation, key units, axis bounds, and scope exclusions. With no output schema present, it could ideally say more about the returned form or the effect of the language parameter, but the tool is simple enough that an agent can correctly invoke it from this definition.

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 0%, so the description must compensate. It does add semantic value by specifying dioptres and degrees and the axis range, but it does not explain the language parameter or clarify the role each parameter plays in the transposition. Parameter names are reasonably self-explanatory, but the compensation is only partial.

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 ('Transpose'), a precise resource ('sphere/cylinder notation'), and the key invariant ('without changing the prescription'). It is clearly distinguishable from the sibling calculation tools and knowledge lookups, even without naming them.

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 intended use is implied by the operation itself, and 'Does not diagnose or generate prescriptions' provides a negative boundary. However, it does not explicitly say when to choose this over calculate_decentration or calculate_prism, nor does it offer an alternative-tool pointer.

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