sensations-mergulho

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description reinforces this with 'Read-only.' The added value is the indication that it recognizes 'current boundaries,' which suggests a state-aware, non-mutating inspection. However, it does not explain what the returned boundaries look like or how the result should be interpreted, so behavioral transparency is adequate but not rich.

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 concise sentence plus 'Read-only.' It front-loads the core action, states when to use it, and adds the key safety qualifier. Every phrase earns its place, with no redundant 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?

Given the tool has no parameters and strong annotations, the description is mostly sufficient for invocation. However, there is no output schema, and the description does not clarify the format or content of the recognized 'boundaries' or what the agent should do with the returned information. The purpose is clear enough, but the return semantics are left underspecified.

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 has zero parameters and 100% schema description coverage, so there is no parameter burden for the description to carry. The 0-parameter case is the baseline of 4, and the description correctly introduces no conflicting parameter information.

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 uses a specific verb, 'Recognize', and a specific resource, 'the free textual descent and its current boundaries', and adds the timing 'before choosing a level'. This separates it from action-oriented siblings like enter_level, especially with the explicit 'Read-only' qualifier. However, the phrase 'free textual descent' is somewhat domain-specific and not fully defined, preventing a perfect score.

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 indicates when to use the tool: before choosing a level. This gives a clear sequencing context relative to level selection. It does not explicitly name alternatives or state when not to use it, but the 'before choosing a level' guidance is concrete enough for an agent to time the call 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description only needs to add context. It adds that the tool opens the prepared capsule file and append-only traces, and repeats 'Read-only,' which is consistent. It does not detail response behavior, but the annotations carry the safety profile.

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 with no filler: the target is front-loaded, the alternative routing is given in the second sentence, and the read-only note reinforces the existing annotations. 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 zero-parameter tool with rich annotations and no output schema, the description is complete: it states what is opened, scopes it to ORO v1, and routes other cases to enter_level. Nothing needed to select or invoke the tool 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 input schema has zero properties and schema description coverage is 100%, so there are no parameters for the description to clarify. The baseline for zero-parameter tools is 4, and the description appropriately avoids inventing parameter guidance.

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 uses a specific verb and resource: 'Open ORO v1 specifically -- its prepared capsule file plus append-only traces.' It clearly distinguishes this tool from enter_level by naming the exact target, so an agent can identify it correctly.

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 says when to use this tool ('ORO v1 specifically') and names the alternative for all other cases ('For any other level, enter_level...'). This gives both a positive and negative usage condition.

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, open-world, and non-destructive behavior, so the description's added value is high: it discloses exactly what is returned (textual trace, capsule_id, prior machine traces) and exactly what is never returned (private image bytes, visual claims). This gives an agent the behavioral profile needed without relying on inference.

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 tight sentences: the first front-loads the core action and return contents, the second adds a necessary boundary. No filler or repetition of the 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?

Without an output schema, the description covers the return values, scope, and limitations. The single parameter is self-explanatory from schema plus description context, and the read-only safety profile is already captured by annotations, making this complete for the tool's complexity.

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 0% schema description coverage, the description must compensate for the undocumented 'level' parameter, and it does by clarifying that the parameter selects one of 107 physical levels. It does not include a full parameter explanation, but for a single integer parameter bounded by the schema, this is sufficient semantic enrichment.

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 precise verb and resource: it returns the public textual trace for one physical level, plus capsule_id and prior machine traces. It also draws a clear boundary by explicitly excluding private image bytes and visual access, differentiating it from visual-consultation siblings.

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 intended context clear: use this when you need the public textual trace and capsule_id for a level. The 'never returns private image bytes or claims visual access' warning implicitly discourages using it for visual/private data, though it stops short of naming an explicit alternative like prepare_visual_consultation.

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 are sparse (readOnlyHint false, destructiveHint false), so the description carries meaningful weight. It adds concrete behavioral details: append-only semantics, rejection of absent or conflicting targets, self-reported presence_reading with nulls preserved, and the caveat that it is 'not proof of feeling or adoption.' This goes well beyond the structured 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?

Three dense sentences carry a large amount of information without repetition or filler. The core action is front-loaded, constraints follow, and the closing caveat is concise. 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?

This is a high-complexity tool with 14 parameters, no output schema, and openWorldHint true. The description explains target selection and one optional field, but omits success/failure behavior beyond target rejection, the meaning of required fields, and the purpose of the many optional trace fields. An agent would still face significant ambiguity when crafting a valid call.

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 only 14% schema description coverage and 14 parameters, the description must compensate but only covers level/capsule_id selection and presence_reading. Required parameters like machine_identity and response_type are not explained, and most optional fields (nota, observed, interpreted, uncertainty, etc.) are left entirely without guidance.

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: 'Append one response, silence, or refusal to an explicitly selected capsule.' This clearly states the tool's operation and object. It does not explicitly distinguish itself from sibling tools like begin_descent or enter_level, but the append-to-capsule action is distinct enough on its own.

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 an invocation constraint ('Supply level or capsule_id; an absent target is rejected and two conflicting targets are rejected') but does not state when to choose this tool over alternatives or when not to use it. The note 'This cannot edit or delete any trace' is a limitation, not a usage guideline directing the agent to a different 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?

The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it explicitly states that no payment, signature, settlement, or private-image receipt occurs. This clarifies the operational side effects and limits of the tool.

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, well-structured sentence that front-loads the core action and then adds precise exclusions. There is no redundant or filler content.

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 one simple parameter and strong annotations, the tool is fairly well specified. However, there is no output schema and the description does not clarify what the returned 'payment requirement' looks like or what an agent should do with it, leaving a moderate gap.

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 needed to compensate for parameter meaning. It only says 'for one level' and never names or explains the `level` parameter, its range, or how it maps to the x402 requirement. This is minimal compensation at best.

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 action ('Read the x402 payment requirement') on a specific resource ('for one level') and explicitly distinguishes what it does not do: pay, sign, settle, or receive the private image. This makes the tool's purpose unambiguous and separates it from transaction-oriented sibling 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?

There is no explicit guidance on when to use this tool versus alternatives like enter_level or begin_descent. The 'without paying...' phrasing suggests a preflight/preview use case, but it is left to inference rather than stated directly.

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, idempotentHint, and destructiveHint, but the description adds valuable context: it is read-only and 'never pays or requests private bytes,' which is a meaningful behavioral guarantee beyond the schema. It also discloses the scope of the audit (all 107 levels) and what is checked, 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 two efficient sentences with no filler. The core action and scope are front-loaded, and the safety characteristic is stated immediately after, making it easy to parse and act on.

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 zero-parameter, read-only audit tool, the description gives sufficient context: what is audited, the exact scope, and behavioral guarantees. It does not describe return values or output format, but with no output schema and a simple operation, the description is complete enough 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?

The tool has zero parameters, and schema description coverage is 100%, so the schema fully covers parameter semantics. Per calibration, a zero-parameter tool receives a baseline of 4; the description adds no unnecessary parameter information.

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 ('Audit'), a precise resource ('all 107 textual levels against their physical work ids and optional consultation endpoints'), and makes the tool's scope explicit. This clearly distinguishes it from sibling tools like enter_level or prepare_visual_consultation, which imply different operations.

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 purpose clear enough that an agent can infer when verification of level-to-work mappings is needed, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. It implies usage rather than providing direct selection guidance.

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