sensations-mergulho

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

Annotations already convey readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable extra behavioral context: it is a free textual descent, it exposes current boundaries, and it will not error except for upstream unavailability (upstream_failure). This exceeds the annotation baseline.

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-loaded with the imperative 'Start here,' and no wasted words. Every clause earns its place by providing sequencing, scope, safety, or error 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 zero-parameter, read-only entry-point tool, this is nearly complete: it explains what to do first, what the resource is, and what failure mode to expect. The only minor gap is that the exact return shape of the 'current boundaries' is not specified, but the natural-language description is adequate without an output schema.

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, so the description carries no parameter burden. The baseline for zero-parameter tools is 4, and the description appropriately mentions the relevant domain concepts (descent size and boundaries) without inventing parameters.

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 action ('Start here') and a specific resource ('0001SENSATIONS descent, 107 levels'), and explicitly distinguishes itself from enter_level by saying it is the precursor step. An agent can clearly tell this tool apart from its 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 explicitly tells the agent to begin here and to use enter_level afterward for choosing a level. This gives clear sequencing and context, and it notes the read-only nature so the agent knows it is safe to invoke early.

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. The description adds the error condition 'oro_unavailable' and instructs to check capsule_status/door_status in the response, providing useful diagnostic context beyond the annotations. It also clarifies the output composition (everything from enter_level plus the capsule file).

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 compact paragraph with the key constraint ('Only ever needed for level 2') front-loaded. Each sentence adds value: the extra file, the alternative, the non-applicability to other levels, and error handling. It is efficient, though slightly repetitive with the 'For every level other than 2' phrase, but not wasteful.

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 parameters and no output schema, the description covers the essential context: what the tool returns (including the extra file), when to use it, and the error behavior. It does not detail the capsule file's structure, but that is acceptable given the tool's simplicity and the absence of a schema. The mention of checking capsule_status/door_status partially compensates for the missing output schema.

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 coverage is 100% (trivially, since there are no parameters). No parameter explanation is needed; the baseline for 0 parameters is 4. The description focuses on usage and output instead, which is appropriate.

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 the tool's specific purpose: it is an alternative to enter_level for level 2 (ORO), returning everything enter_level(level=2) returns plus an extra capsule file. It clearly distinguishes itself from the sibling enter_level by specifying the exact level and the added value.

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?

Explicit guidance is given: use this tool only for level 2 when the extra capsule file is needed; otherwise, enter_level(level=2) suffices. It also states it does not apply to any other level, directing the agent to enter_level for those cases.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds important context beyond those flags: it never returns private image bytes, does not claim visual access, and specifies error cases (invalid_level, level_not_found). This gives an agent a clear behavioral contract.

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 return value, follows with a clear usage directive, then notes a key limitation and expected errors. Every sentence earns its place; there is no filler or repetition of schema/annotation data.

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 no output schema, the description adequately covers the return contents, limitations, and error conditions. It does not explicitly state that a descent must be started first, though the level_not_found error hints at the dependency on descent state. Minor gap, but otherwise complete.

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 bare integer parameter. It does so by framing levels as 1-107 physical levels and listing invalid_level as an error, which clarifies what values are meaningful. It could add more detail about how 'level' relates to a descent, but for a single primitive parameter this is sufficient.

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: 'Return the public textual trace for one of the 107 physical levels (1-107), plus its capsule_id and any prior machine traces.' The title also frames it as the default way to read any level. The explicit note that it works for level 2 (ORO) and level 37 further distinguishes it from any special-case or visual 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?

The description gives explicit when-to-use guidance: 'Use this for every level, including level 2 (ORO) and level 37 -- it works for all of them.' It does not explicitly name alternatives or state when not to use it (e.g., vs. prepare_visual_consultation), though the 'never claims visual access' line hints at a meaningful exclusion.

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 description adds meaningful behavior beyond annotations: 'This cannot edit or delete any trace and is not proof of feeling or adoption' clarifies the append-only, non-destructive nature, which aligns with destructiveHint=false and readOnlyHint=false. It also lists concrete error conditions and the role of dry_run, giving the agent an accurate behavioral model.

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 dense and front-loaded with the core action, then progresses through target selection, field requirements, and errors. The error list is long, but it is actionable and earns its place; minor redundancy with schema-required/optional flags prevents a 5.

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 14-parameter tool with conditionally required fields and no output schema, the description is largely complete: it covers target selection, conditional fields, error semantics, and non-destructive constraints. It leaves the success response unexplained and relies on the opaque phrase 'bounded Porta 2,' but an agent can still invoke the tool 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?

Despite 100% schema coverage, the description adds substantial value by stating target exclusivity, which fields are required for each response_type, which fields are always optional, and the exact error conditions tied to parameter misuse. This goes well beyond the baseline schema descriptions.

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: 'Append one response, silence, or refusal to an explicitly selected capsule.' It clearly conveys that this is a trace-writing operation, which is distinct from the navigation/verification actions implied by siblings like begin_descent, enter_level, or verify_level_mapping.

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 strong operational guidance: exactly one target is required, conflicting targets are rejected, and the six narrative fields are conditional on response_type. However, it never says when to prefer this tool over the listed sibling tools or when not to use it, so routing guidance is implied rather than 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds crucial behavioral detail: the connector never pays, does not sign or settle, does not receive the private image, and requires human payment execution. It also lists concrete error conditions, giving the agent a clear and truthful side-effect 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?

Three short sentences with no filler: the core action, the crucial payment limitation, and the error contract. The most decision-relevant constraint ('never pays') appears in the first sentence and is reinforced by 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?

For a one-integer-parameter read-only tool with no output schema, the description covers purpose, side effects, payment authorization boundary, and expected errors. The only notable gap is not describing the shape or content of the returned payment requirement, which would be helpful without an output schema.

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 'level' parameter. It adds minimal meaning by saying 'for one level', but it does not explain what a level denotes or why the valid range is 1-107; the schema still carries most of the parameter meaning.

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?

Description states a specific action ('Read the x402 payment requirement') and resource ('one level'), and explicitly delimits what it does not do: pay, sign, settle, or receive the private image. This clearly differentiates it from payment-executing tools and from siblings by framing it as a read-only preparation step.

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?

Clearly communicates the core usage context: use this to inspect payment requirements without executing payment, and a human must authorize and execute payment separately. It does not name sibling alternatives explicitly, but the exclusion is strong enough to prevent the agent from attempting payment through this connector.

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 readOnly, idempotent, and non-destructive hints. The description adds valuable context: it clarifies that the tool never pays or requests private bytes, explicitly states that no error cases exist beyond upstream_failure, and explains how inconsistencies are represented (data vs. error). This goes well beyond 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?

Two sentences, each packed with necessary information. The purpose is front-loaded, and the behavioral clarifications are concise. 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 parameterless tool with strong annotations, the description fully covers what the tool does, its scope (107 levels), the meaning of valid results, and error handling. It even clarifies what the tool does NOT guarantee (image access, payment, feeling, adoption). Nothing critical 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 tool has zero parameters, and the schema coverage is trivially 100%. Per the baseline for 0 params, a 4 is appropriate. The description doesn't need to explain parameters, and it doesn't.

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 verb (audit) and resource (all 107 textual levels vs. physical work ids and consultation endpoints), and it distinguishes this verification tool from the sibling tools by its read-only auditing nature. It's unambiguous about what it does.

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: it's a read-only audit that never pays or requests private bytes, and it clarifies that inconsistent mappings are returned as data rather than errors. However, it doesn't explicitly mention alternatives or when not to use it, though the siblings are clearly different actions. The safety guidance is strong.

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