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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description goes beyond them by disclosing that the server performs the fetch (so https public URLs or small data: URIs are required) and that 360° images are validated as 2:1 equirectangular. It stops short of covering failure behavior or whether re-adding duplicates images, which keeps it off a 5.

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 dense sentences, front-loaded with the primary action and the returned artifact before the alternatives. The nested parenthetical about local 360° files is slightly awkward but carries non-redundant routing information.

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?

No output schema exists, yet the description states what is returned (stored img.pedra.ai URLs) and how they are used downstream. Combined with the sibling routing and 360° validation notes, an agent has everything needed 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the acceptable URL forms and the network-fetch implication, plus the semantic consequence of passing type "360" (equirectangular check and tour eligibility).

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 (add) and resource (photos to a property) and explicitly scopes the input mechanism to URLs fetched by the server. It distinguishes itself from the sibling tools pedra_create_upload_link and pedra_add_local_panoramas by name.

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 explicit routing: use pedra_create_upload_link for device photos, pedra_add_local_panoramas for local 360° files. It also names the downstream consumers (editing, video, tour tools) that the returned URLs feed, which tells the agent when this call is a prerequisite.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds valuable operational context — local-disk-only access, 10-file batching under the 50 MB request limit, the ~33 MB per-file cap, and the order-becomes-walking-order effect — but does not describe auth requirements or failure handling in depth. Strong added context against an already-covered 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?

Front-loads the critical LOCAL-ONLY framing and is dense with useful detail, but it is delivered as a single long paragraph. Every sentence earns its place, though the batching and size-limit clauses could be more scannable.

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 steps in by describing the return value (added photos with imageIds as scene ids, plus failed files each with their path). Combined with limits, batching and the sibling cross-reference, an agent has everything needed to call this 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%, so both parameters are documented structurally, giving a baseline of 3. The description goes beyond that by explaining that the supplied order becomes the walking order used by pedra_create_virtual_tour and by specifying accepted image formats (2:1 equirectangular JPEG/PNG/WebP), adding meaning the schema alone doesn't convey.

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 (upload/add) and resource (360° photo files from local disk into a property), and explicitly distinguishes itself from the sibling pedra_create_upload_link. An agent can tell immediately what this does and how it differs from the alternative path.

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 explicit selection criteria: prefer this over pedra_create_upload_link whenever the photos are files on this computer, and use the upload link instead for files over ~33 MB. Both the when and the when-not are named.

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=false and destructiveHint=false, but the description adds substantial behavioral detail beyond them: credit cost formula for sequential linking, free option for linking none, async behavior, and the need to poll until status ready. This is exactly the kind of operational context an agent needs for a mutating, credit-consuming, asynchronous 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 front-loaded with the core action, then efficiently packs linking behavior, cost implications, and required polling into three sentences. Every sentence earns its place with no redundant restatement of the 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?

For a mutating tool with annotations covering safety hints, no output schema, and full parameter schema coverage, the description supplies the critical missing operational context: async execution, cost model, and polling instructions. An agent has enough information to call this correctly without opening other 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 coverage is 100%, so the baseline would be 3. The description adds meaning beyond the schema by explaining the effect of the linking parameter, including the difference between sequential and none and the resulting credit cost. It also clarifies that new rooms are appended and linked in walking order, which reinforces the scenes parameter semantics.

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: add rooms to the end of an existing virtual tour. This clearly distinguishes it from sibling tools like pedra_create_virtual_tour and pedra_update_virtual_tour, which create or modify tour metadata rather than append scenes.

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 first sentence establishes clear context for when this tool applies: extending an existing tour. It also instructs the agent to poll pedra_get_virtual_tour until status is ready after invocation. However, it does not explicitly state exclusions or contrast with alternative sibling tools beyond the polling helper.

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=false, destructiveHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds the return value (blurred image URL), which is genuinely useful, but says nothing about credit cost, whether the source is modified, or whether this is asynchronous.

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, zero waste, purpose front-loaded before the return-value note. Every clause 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 2-parameter tool with full schema coverage and no output schema, the description supplies the one thing the schema omits (the returned blurred image URL). Minor gaps like cost or sync/async behavior remain but are not critical here.

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%, so both parameters are fully documented in the schema, including the fallback to pedra_create_upload_link for unreachable device photos. The description adds no parameter detail beyond that, so the 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+resource (blur objects in an image) with concrete examples of the targets (faces, license plates) and the intent (privacy). It is distinguishable from siblings like pedra_remove_object or pedra_enhance, though it never names an alternative to sharpen the contrast.

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 'for privacy' implies the use case, but there is no explicit when-to-use vs. when-to-use-something-else guidance and no mention of the sibling tools an agent might confuse this with (e.g. pedra_remove_object).

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 this is a non-read-only, open-world, non-destructive operation. The description adds context annotations cannot convey: the returned propertyId and appUrl, and the implicit auth distinction (upload link works 'no login'). Permissions for creation itself are not spelled out.

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 purpose and return values, then the optional workflow guidance. 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?

No output schema exists, and the description compensates by naming the return values (propertyId, appUrl). It also closes the loop on the natural next step (photos via upload link or appUrl), so an agent has everything needed to call it and act on the result.

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?

Only one parameter (name) and schema description coverage is 100%, so the schema already explains it as the listing address. The description adds no syntax, format, or default guidance for name, so the 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+resource ('Create a new Pedra property') and immediately names the return values. It also references the sibling tools (pedra_create_upload_link, pedra_list_property_images) that handle the adjacent photo workflow, so an agent can place it in the tool set without opening schemas.

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 explicit routing advice for the follow-on photo step: use pedra_create_upload_link for device photos (noting it needs no login), or hand the user the appUrl and then call pedra_list_property_images. It does not say when creating a property is appropriate relative to e.g. pedra_list_properties, but the alternatives it does name are actionable.

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 only declare read-only=false/openWorld=false/destructive=false; the description adds substantial context beyond them: no login required, 24-hour expiry, that a property is created when propertyId is omitted, that type '360' causes non-360 uploads to be refused, and that 360° photos are auto-recognised.

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 purpose and validity constraint, then routing and follow-up steps. Dense with useful information, though the trailing parenthetical about the local server is somewhat long and could be tighter.

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?

Covers purpose, access model, expiry, side effects, parameter behaviour, the downstream workflow, and the local-server alternative. With no output schema and full schema coverage, nothing essential 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%, so the baseline is 3, but the description adds real semantics: propertyId omission triggers property creation, and type '360' enforces refusal of other content. It slightly restates the schema's own type/name descriptions, keeping it from a 5.

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 ('Get a link where the user... uploads photos... into a property') with clear scope: no login, 24-hour validity. It is readily distinguishable from siblings like pedra_add_images_to_property and pedra_add_local_panoramas, which are named in the routing text.

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 when-to-use: 'whenever the photos are files on the user's device that weren't attached to the chat.' It also names the alternative path for local files (passing a local imageUrl or using pedra_add_local_panoramas), and states the follow-up sequence (wait, then pedra_list_property_images or pedra_create_virtual_tour).

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 declare a non-read-only, open-world, non-destructive write, and the description adds genuine behavioral context beyond them: the call blocks server-side for up to ~10 minutes and returns the rendered URL inline rather than requiring a polling step. That latency and return-shape disclosure is exactly what an agent needs to avoid a timeout surprise. It stops short of 5 because no auth, quota, or failure behavior is mentioned.

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, fully front-loaded: the action first, then the operational caveat. Nothing is padded and every clause carries information.

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 heavy composite tool with 8 parameters, nested objects, and no output schema, the description covers the crucial return value and blocking behavior well. But it leaves the multi-input composition story (music library, voiceover dependency, branding, aspect ratio) entirely to a low-coverage schema, so the definition is adequate rather than 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 only 25% across 8 parameters, so the description carries a heavier burden — yet it only restates 'a list of images' and says nothing about music, voice, branding, ending titles, or property characteristics. Nested structures like music.track and voice.audioId carry their own schema text, but the top-level composition options are undocumented in 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 states a specific verb and resource: 'Create a property video from a list of images.' It is immediately clear what the tool produces and its input source. It does not, however, differentiate itself from the sibling pedra_update_video, which an agent would need to distinguish creation from modification.

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 no when-to-use or when-not-to-use guidance and names no alternatives, even though the sibling list contains pedra_update_video, pedra_generate_voice, and pedra_music_library which are all relevant to composing a video. The only routing hint ('get a link from pedra_create_upload_link') lives in the schema, not the description.

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?

Goes well beyond the annotations (readOnly=false, openWorld=true, destructive=false) by disclosing that a tourId returns immediately, that the build takes ~10s/room, that the caller must poll pedra_get_virtual_tour until status is 'ready', and the exact credit formula per linking mode.

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?

Information-dense and front-loaded with the outcome, then inputs, then linking costs, then async behavior. Slightly long for a single paragraph, but nearly every clause carries unique operational value.

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 compensates by explaining the immediate return value (tourId), the polling requirement, and the terminal status — everything an agent needs to invoke and follow up 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 already 100%, so the baseline is 3, but the description adds real semantic value: what 'sequential'/'smart'/'none' actually do, their relative cost, and the walking-order meaning of the scenes array.

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 ('Build a hosted 360° virtual tour') plus the concrete outputs (shareable link and embed code), clearly distinguishing it from siblings like pedra_add_virtual_tour_scenes or pedra_update_virtual_tour.

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?

Explicitly covers the two mutually exclusive input paths (pass scenes in walking order, or just propertyId to use all 360° photos), names the alternative linking modes with their tradeoffs, and states the 'one tour per property' constraint.

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=true and destructiveHint=false. The description adds that it reads 'plan and remaining credits', providing specific data beyond annotations. This is useful context for the agent.

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 short sentences front-load the core purpose and behavioral guarantee. Every word is informative; no wasted text.

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 tool without output schema, the description sufficiently explains what is returned (plan and remaining credits). It fully covers the agent's needs.

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?

No parameters exist, so baseline is 4 per rule. The description correctly implies no input is needed.

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 title 'Get credits' and description clearly specify the verb 'Read' and the resource 'account's plan and remaining credits'. It unambiguously distinguishes from sibling tools that perform image editing 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 explicitly states it never deducts credits, implying safe usage. While no alternatives are mentioned, the zero-parameter interface makes usage straightforward and self-evident.

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 it is a non-read-only, open-world, non-destructive operation, so the safety profile is covered. The description adds one genuinely useful behavioral fact that annotations do not convey — that the result is returned as a new edited image URL rather than modifying in place. It says nothing about cost/credits, latency, or whether the source image is preserved.

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, no filler, and the core purpose is front-loaded with the example and return value following. Nothing is redundant.

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 two-parameter tool with full schema coverage, the description covers what it does and what it returns, which matters since there is no output schema. It is slightly thin on routing among edit siblings and on cost/side-effect behavior, but nothing required to invoke 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 description coverage is 100%, so both parameters are fully documented in the schema, including the accepted imageUrl forms and the fallback to pedra_create_upload_link. The description only echoes the prompt concept via its example and adds no syntax or format detail beyond the schema, so the 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 and resource ('edit an image') plus the mechanism ('from a natural-language instruction') and gives a concrete example. It does not, however, distinguish itself from the many specialized edit siblings such as pedra_remove_object, pedra_furnish, or pedra_enhance, so the agent cannot tell from the description alone when this generic prompt-edit is the right choice.

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 only usage signal is the example instruction ('paint the walls sage green'), which implies an open-ended edit. There is no guidance on when to prefer this over the many narrower edit tools in the sibling list, and no exclusions or prerequisites 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?

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is already covered. The description adds the return value (emptied image URL), which is useful given there is no output schema, but says nothing about cost (pedra_credits exists), whether the source image is preserved, or processing behavior.

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 short sentences, front-loaded with the action and followed by the return value. 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 single-parameter tool with a fully documented schema, the description covers the action and the return shape adequately. The only gap is usage context relative to siblings, which is minor given the tool's simplicity.

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 itself documents the accepted input forms (https URL, data URI, local path) plus a fallback to pedra_create_upload_link. The description adds no parameter meaning beyond that, 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 and resource: remove all furniture and objects from a room, producing an empty space. It is distinguishable from the sibling pedra_remove_object (single object removal) by the word 'all', though it never names that 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?

Usage is only implied by the description; there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as pedra_remove_object or pedra_furnish. An agent can infer the scenario but must reason about sibling selection itself.

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=false, destructiveHint=false and openWorldHint=true, so the mutation/safety profile is covered. The description adds the return contract ('Returns the enhanced image URL'), which is genuinely useful since there is no output schema, but says nothing about processing time, async behavior, or credit consumption.

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, zero filler, with the core action and the return value front-loaded. Nothing is wasted.

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 two-parameter tool with no output schema, stating the effect and the returned URL covers the essentials an agent needs to invoke it. The only real gap is sibling routing, which is a usage-guideline concern rather than a structural omission.

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%, so the schema already fully documents both imageUrl and preserveOriginalFraming, including the cross-reference to pedra_create_upload_link. The description adds no parameter detail beyond that, making the baseline 3 correct.

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 (enhance) and resource (real-estate photo) and enumerates the concrete effects: lighting, color, sharpness. It is clear, but it does not differentiate itself from the near-identical sibling pedra_enhance_and_correct_perspective, leaving the agent to guess which enhancement to pick.

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 at all. With siblings like pedra_enhance_and_correct_perspective, pedra_edit_via_prompt, pedra_renovation and pedra_furnish all plausible for a given photo, the description never says which condition selects this tool over those.

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 non-destructive (destructiveHint=false) and openWorld. The description adds that it returns the corrected image URL, which is genuinely useful given no output schema exists. It does not clarify whether the original is left untouched or whether the operation consumes credits.

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 short sentences: the action with its clarifying parenthetical, then the return value. Zero waste and front-loaded.

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 two-parameter tool with no output schema, the description covers the action and the return type, and annotations cover safety. It is nearly complete, missing only the sibling-differentiation and any credit/permission implications.

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%, so both parameters (imageUrl, preserveOriginalFraming) are fully documented in the schema, including the upload-link fallback. The description adds no parameter detail beyond that, 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 pair and resource: enhance a photo AND correct vertical/horizontal perspective, with the parenthetical clarifying what correction means (straighten walls and lines). This distinguishes it from the sibling pedra_enhance, which presumably only enhances, though the description never names that 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?

No when-to-use or when-not-to-use guidance. It doesn't say to prefer pedra_enhance when perspective correction isn't needed, nor what input constraints apply. The only routing hint (use pedra_create_upload_link for phone photos) lives in the schema, not the description.

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 provide readOnlyHint=false and destructiveHint=false, so the description must add behavioral context. It mentions credit-back subject to eligibility rules, but does not elaborate on eligibility or other behaviors like clearing votes, which is partially captured in 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?

The description is two sentences long, no fluff, and front-loaded with the primary action and key nuance (credit-back on thumbs-down). 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?

Despite 5 parameters, the description does not explain parameter interdependencies (imageUrl/imageId), success/error responses, or the behavior of the empty vote string. No output schema exists, so the description should compensate, but it does not.

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 80%, and the description adds minimal value beyond what the schema already provides. It restates that vote is thumbs up/down and that creditBack is optional, but does not clarify the required relationship between imageUrl and imageId or explain the empty string vote clearing.

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 'Submit thumbs up/down feedback on a generated image', which is a specific verb and resource. It distinguishes well from sibling tools that focus on image editing operations like blur, create video, enhance, etc.

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 for providing feedback with optional credit-back, but does not explicitly state when to use this tool vs alternatives, nor does it explain the eligibility rules for credit-back or when to clear a vote.

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 declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the agent already knows this is a non-destructive generative operation. The description adds the key behavioral fact that this is AI generation producing a staged image URL, but discloses nothing about processing time, failure modes, or cost/credits (despite a pedra_credits sibling).

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 short sentences, the action stated first and the return value second. No filler, no 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 3-parameter, non-destructive generation tool with fully documented schema and annotations, the description covers the essential action and return value even without an output schema. It could say more about outputs beyond the URL (e.g., whether multiple variants are returned), but nothing blocking an agent 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 description coverage is 100% and the schema already documents imageUrl, style, and roomType in detail, including the upload-link fallback. The description adds no parameter meaning beyond that, so the baseline of 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 and resource ('Virtually stage (furnish) a room with AI-generated furniture') and specifies the output ('Returns the staged image URL'). It is clear on its own, but it does not distinguish itself from similarly-named siblings like pedra_empty_room (the inverse) or pedra_renovation, so it falls 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 gives no when-to-use, when-not-to-use, or alternative-tool guidance. With ~26 siblings including pedra_empty_room and pedra_create_upload_link, an agent gets no routing help from the description itself.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the main remaining burden is workflow behavior. The description usefully discloses that it returns an audioId for downstream attachment with synced subtitles, but omits cost/credit consumption and any rate or length constraints beyond the schema's 1000-char note.

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, no filler, and the primary action is front-loaded ahead of the downstream-chaining note. Every clause carries information.

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 correctly compensates by stating the return value (audioId) and how to consume it. For a simple three-param TTS tool this is nearly sufficient; only cost/limits are unaddressed.

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 params are richly documented (voiceId points at pedra_music_library, language defaulting rules, text length cap). The description adds no parameter meaning beyond the schema, 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+resource ('Render a voiceover from a script via text-to-speech') and names the enabling mechanism. It is clearly distinguishable from pedra_generate_voice_script, which is the script-writing sibling, because this tool's output is audio.

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?

Explicitly tells the agent what to do with the result: pass the audioId to pedra_create_video / pedra_update_video as voice.audioId. That is real workflow routing, but there is no when-not-to-use guidance or prerequisite (e.g. credits) noted.

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 declare readOnlyHint=false and openWorldHint=true, so the bar for safety disclosure is partially met, but the description adds genuinely useful behavior: GPT-4o vision actually reads the images, and the return value is raw script text meant to be chained into pedra_generate_voice. It omits cost/credit implications, which matters for a paid-generation sibling set.

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, no filler, with the core action and its downstream handoff front-loaded. Every sentence carries information an agent needs.

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, but the description compensates by stating the return value ('Returns the script text') and its consumer. The remaining gap is operational context such as credit cost and whether images are effectively required despite zero required parameters.

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 67%, so the schema already documents the image source formats, language default, and the propertyCharacteristics label/value pair. The description only adds that facts are optional, which is marginal over the schema's own text.

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 ('Write a short voiceover script from property photos') and immediately distinguishes itself from the sibling pedra_generate_voice by naming it as the downstream consumer. An agent can tell what this produces versus what the voice tool produces without opening either 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 clear context for use (photos + optional facts) and explicitly routes the result to pedra_generate_voice, which is a strong 'when to use' signal. It stops short of saying when NOT to use it or what alternative to pick if no photos exist.

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=true and destructiveHint=false, so safety is covered; the description's real added value is the asynchronous lifecycle disclosure (status can be "processing", "ready" or "failed", with reason) plus the polling directive. It does not mention rate limits or how long processing typically takes, but the async behavior is clearly signposted.

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?

Dense and front-loaded: the return payload comes first, the polling trigger second. The trailing "Read-only." is redundant with readOnlyHint and does not fully earn its place, keeping it just under 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?

With no output schema, the description compensates by enumerating the returned fields and their meaning, and it explains the async status lifecycle the agent must handle. Nothing needed to call a single-parameter read tool 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 description coverage is 100% and there is only one parameter (tourId), whose provenance is already documented in the schema ("Id from pedra_create_virtual_tour or pedra_list_virtual_tours"). The description adds no syntax or format detail beyond that, so the 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 (Get) and resource (virtual tour) and enumerates the payload the agent receives: status with reason, tourUrl, embedCode iframe, scenes and navigation links. This clearly separates it from siblings like pedra_list_virtual_tours and pedra_update_virtual_tour.

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?

"Poll this after pedra_create_virtual_tour or pedra_add_virtual_tour_scenes" gives explicit when-to-use context and names the triggering siblings. It stops short of stating when not to use it (e.g., use list_virtual_tours for discovery), so it is not a full 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 readOnlyHint=true and destructiveHint=false. The description adds context by listing the return fields, which is beneficial 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 with no wasted words. The first sentence defines the tool, the second provides a usage example. Front-loaded and efficient.

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 tool with no parameters and no output schema, the description fully explains what it does and why to use it. Complete for the given 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?

No parameters exist, so the description does not need to add parameter detail. The schema coverage is 100%, achieving the baseline.

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?

Clearly states the tool lists the user's Pedra properties and specifies the fields returned (id, name, photo count, appUrl). However, it does not differentiate from sibling tools like pedra_list_property_images.

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?

Provides an explicit use case (find photos for building a video) but does not mention when not to use or name alternatives.

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=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the output are img.pedra.ai URLs ready for downstream tools, and in 360 mode the imageIds are the scenes of a virtual tour. It stops short of documenting ordering/pagination, but adds real value over 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?

Three tight sentences, each earning its place: what is returned, where to get the input, and the alternate mode. Front-loaded with the primary 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?

There is no output schema, yet the description covers the return value (img.pedra.ai URLs), the input source (pedra_list_properties), and the mode switch. Nothing an agent needs to invoke 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 the baseline is 3, but the description adds meaning beyond the schema: the "360" value's imageIds are the scenes of a virtual tour, and propertyId is sourced from pedra_list_properties. That is semantic context the schema alone does not convey.

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 (list the photos in a Pedra property) and specifies the return form (img.pedra.ai URLs). It clearly distinguishes the default photo listing from the 360 mode, so an agent can tell what this tool produces 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?

Explicitly routes the agent to siblings: get propertyId from pedra_list_properties, and the returned URLs feed directly into pedra_create_video or the image-editing tools. It also states the condition that selects the alternate mode (pass type "360").

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=true, destructiveHint=false, and openWorldHint=true, so 'Read-only' is partly redundant. The description does add value beyond the annotations, though: it discloses result ordering (newest first) and the shape of the returned records (status, share link, room count), which matters because no output schema exists.

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 short sentences with no filler. The core action and ordering lead, the optional filter follows, and the safety note is a compact trailing clause. Nothing wastes space.

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 usefully enumerates the returned fields and ordering, and the annotations cover the safety profile, so an agent has enough to call it correctly. Minor gaps remain: no mention of pagination or result-size limits on an account-wide listing.

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?

There is a single optional propertyId parameter and schema description coverage is 100%, with the schema already stating 'Only this property's tour.' The description's 'Optionally only one property's' conveys the same meaning in prose but adds no format or semantic detail beyond the schema, so the 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 and resource ('List the account's virtual tours') plus the ordering and the fields returned (status, share link, room count). The scope clearly differs from pedra_get_virtual_tour, but the description never names that sibling to make the distinction explicit, which is the only thing separating it from 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 phrase 'Optionally only one property's' implies the filtering use case, and the plural 'tours' implies this is the bulk-listing option versus a single-tour getter. However there is no explicit when-to-use statement, no when-not condition, and no named alternative, so usage is left 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the trailing 'Read-only.' adds no new information. The description does add useful behavioral context by disclosing the catalog's structure (genres plus per-genre languages and voices), but says nothing about caching, freshness, or how large the result may be.

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 carries the catalog contents, and the content description is not padded. The appended 'Read-only.' is redundant with the annotations and is the only wasted text.

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 input parameters, no output schema, and safety fully covered by annotations, the description's job is mainly to explain what comes back — which it does by naming the genre keys, languages, and voices. Complete enough to call correctly, with only minor omissions such as result size or format.

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 zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description usefully clarifies the shape of the returned catalog entries (genre keys mapped to languages and narration voices), which is the closest analogue to parameter meaning for a filterless listing tool.

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?

It states a clear verb-plus-resource ('List the background-music catalog') and then enumerates exactly what the catalog contains: `music.track` genre keys, voice languages, and narration voices per genre. That is far more specific than a bare title restatement, though it does not explicitly contrast itself with the voice-generation siblings it feeds into.

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?

Calling this a list of 'valid `music.track` values' implies it is a lookup/reference step used before invoking a generation tool, which is reasonable implied usage. However, no when-to-use or when-not-to-use condition is stated and no sibling (e.g. pedra_generate_voice) is named as the downstream alternative.

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=false, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds the return value ('cleaned image URL'), which is useful since no output schema exists, but says nothing about credits consumed, processing time, or whether the source image is modified in place.

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 short sentences, front-loaded with the operation and followed by the return value. No filler, though it is arguably too terse given the gaps elsewhere.

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 two-parameter tool with a fully documented schema and no output schema, the description covers what the tool does and what it returns. Missing only usage routing and cost/behavioral context, which are minor here.

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 details acceptable input forms (https URL, data URI, local path) plus the pedra_create_upload_link fallback. The description adds no parameter meaning beyond what the schema provides, so the 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 (remove) and resource (an object from an image via a mask), and it names the artifact it returns (cleaned image URL). It does not distinguish itself from sibling image-editing tools like pedra_enhance or pedra_blur, but the mask-based removal is self-evidently distinct.

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 guidance on when to use this tool versus alternatives (e.g. pedra_edit_via_prompt for text-driven edits). 'Using a mask' implies a precondition but nothing states when-not to use it or what happens if no mask region is found.

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=false, destructiveHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds that the output is a renovated image URL, which is useful, but it omits credit/cost implications and whether the result is a new asset versus an in-place edit.

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 short sentences, operation first and return value second, with no filler. Everything stated 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 4-parameter generation tool with a fully documented schema and no output schema, the description covers the action and the return value adequately. Additional context on cost or how it relates to sibling renovation tools would make it 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 100% and the schema documents each parameter thoroughly, including the upload-link fallback for imageUrl, so the baseline of 3 applies. The description only restates the optional furnished/empty notion already covered by the furnish property.

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 (renovate) and resource (space) and enumerates the covered surfaces (walls, floors, finishes). It does not distinguish itself from close siblings like pedra_furnish or pedra_empty_room, which overlap on the furnished/empty dimension, so the agent must infer the boundary.

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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named. The description never explains why an agent would pick this over pedra_furnish, pedra_empty_room, or pedra_edit_via_prompt, all of which operate on the same kind of input.

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=false, destructiveHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds the return shape ('Returns the image URL with the new sky'), which matters because there is no output schema, but says nothing about whether the source image is modified, credit cost (a pedra_credits sibling exists), or failure modes.

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 short sentences, zero filler, with the capability stated first and the return value second. Nothing could be removed without losing information.

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 two-parameter, non-destructive edit tool it covers purpose and return value, and the schema carries the input detail. The one gap is that skyStyle is an 'optional named sky style' with no enumeration of valid names in either the schema or the description, leaving the agent unable to pick a value confidently.

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%, so the schema already documents both parameters, including the detailed imageUrl sourcing rules and the upload-link fallback. The description adds no parameter-level meaning beyond that, so the 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 and resource ('Replace ... sky') plus a concrete condition ('dull or overcast') and an explicit outcome ('clear blue'). It does not differentiate itself from siblings like pedra_edit_via_prompt or pedra_enhance, which an agent might reasonably consider for the same job.

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 'dull or overcast sky' implies the trigger condition, so usage is inferable. There is no explicit when-not guidance or named alternative for sky edits that could be done via pedra_edit_via_prompt.

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?

With annotations covering only safety hints, the description carries the behavioral payload and does so well: it explains the incremental re-render/credit-cost model, that reordering/music/voice/branding/text re-stitch for free, that the call blocks until rendered, and that it returns the new video URL. This is real value beyond the structured fields.

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, front-loaded with identity, then the cost/behavior model, then the return value. No filler; every clause adds actionable information.

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 9-parameter nested-object mutation with no output schema, the description covers cost behavior, omission defaults, blocking, and the return value. It omits guidance on a few nested params, but nothing critical for a 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 only 33% across 9 parameters, so the description must compensate, and it does for the high-impact ones (videoId, images, omission semantics for nested audio/text/branding objects). It still leaves several nested fields (isVertical, propertyCharacteristics, watermark details) to the schema, so not a perfect 5.

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+resource ('Edit an existing video (by videoId)') and implicitly distinguishes itself from pedra_create_video and pedra_edit_via_prompt by scoping to editing an existing render. An agent can identify the tool from the first clause alone.

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 explicit operational rules: omit `images` to keep the current timeline, omit `music`/`voice`/`branding`/ending text to leave them unchanged. It does not name a sibling alternative (e.g. pedra_edit_via_prompt) or state when-not-to-use, so it stops 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 destructiveHint=true and openWorldHint=true; the description adds real value on top by stating the operation is free and instant and that the public link reflects the change immediately. It stops short of calling out irreversibility or confirmation requirements for the destructive removals, which is what a 5 would need.

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-loads the core purpose, then lists the supported mutations, then gives the operational facts and the helper-tool pointer in two short sentences. Dense but every clause maps to a distinct capability; only the parenthetical about the first scene borders on restating the schema.

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 10-parameter destructive mutation tool with no output schema, the description covers what changes, the side effects on the public link, and where to source sceneIds. It omits failure behavior and whether removed links/photos are recoverable, which are the remaining gaps an agent would want.

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%, so the baseline is 3. The description groups operations and maps them to parameters (rename → name/sceneNames, reorder → sceneOrder, remove → removeScenes, links → links), but most of that detail is already in the schema and it adds no extra syntax or constraint 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?

States a specific verb (Change/edit in place) and resource (virtual tour), then enumerates the concrete mutations supported: rename tour/rooms, reorder, remove rooms, replace links, restyle navigation. It is clearly distinguishable from sibling tools like pedra_create_virtual_tour and pedra_add_virtual_tour_scenes because it operates on a finished tour rather than building one.

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?

"Change a finished virtual tour in place" scopes usage to an existing, completed tour, and it explicitly routes the agent to pedra_get_virtual_tour for sceneIds. It does not state exclusions (e.g. don't use for adding scenes – that's pedra_add_virtual_tour_scenes), so it falls short of full when/when-not guidance.

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