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

Goes well beyond the annotations by disclosing that the server performs the fetch (accepted schemes: public https or small data: URI), that 360 photos are validated as 2:1 equirectangular, and what the tool returns (img.pedra.ai URLs). Limits (20/10) are left to the schema, and failure behavior on unreachable URLs is unstated, keeping it from a full 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?

Front-loaded with the core action and return value, then alternatives, then the enum nuance. Dense but every sentence carries routing or behavioral information; the trailing parenthetical about the local server is slightly awkward but genuinely useful context.

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 fills the gap by naming the returned img.pedra.ai URLs and their downstream use, and it covers alternatives and the 360 validation rule. Edge cases like partial failures or invalid URLs are not addressed, but the essentials for correct invocation are present.

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 adds real meaning by explaining that type "360" triggers equirectangular validation and unlocks virtual tours, plus doc-comments in the schema clarify names and propertyId provenance. It doesn't add much beyond the schema on names/ordering, but the enum semantics are enriched.

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?

Specific verb+resource+mechanism: adding photos to a property by URL, with the server fetching each one. It explicitly names the sibling it is not (pedra_create_upload_link for device photos, pedra_add_local_panoramas for local 360 files), so an agent can route correctly without opening any 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?

Gives explicit when-to-use and when-not: device photos go to pedra_create_upload_link, local 360 files go to pedra_add_local_panoramas, and type "360" should be passed for equirectangular photos. It also names the downstream consumers of the returned URLs (editing, video, tour tools).

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

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

Annotations already 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 mark it as a non-read-only, open-world, non-destructive operation; the description adds real value on top by disclosing the two output modes — returning only a URL versus saving into a property's gallery when propertyId is set. It doesn't cover rate limits or auth needs, but the conditional persistence side effect is clearly surfaced.

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 purpose and use case, then the return value, then the one behavioral nuance. No filler; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter image tool with no output schema, the description covers purpose, primary return value, and the optional save-to-gallery behavior, with the schema handling parameter detail. The main omission is any mention of the preserveAspectRatio toggle, which is left entirely to the 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 100%, so the schema already documents every parameter thoroughly, including name and preserveAspectRatio. The description reinforces propertyId behavior but adds little syntax or meaning beyond what the schema provides, so baseline 3 fits.

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 use cases (faces, license plates) for privacy. It does not explicitly contrast with the closest sibling, pedra_remove_object, but the privacy-blurring framing makes its intent distinguishable.

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 the general context (privacy redaction) and notes the conditional behavior of passing propertyId, but names no alternatives and offers no when-not-to-use guidance. Usage is implied rather than spelled out.

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 only flag it as a non-read-only, open-world operation; the description adds real behavioral context beyond that — it returns an edited image URL and, when propertyId is set, persists the result into a gallery and may also save the source photo. It still omits cost/credit consumption and any failure or rate-limit 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?

Three compact sentences, front-loaded with what the tool does and the return value, with the optional propertyId behavior clearly appended. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly states the return value (edited image URL) and covers the key optional side effect of propertyId. It is nearly complete, though it says nothing about credit/cost or limits, which matters given the sibling pedra_credits tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters in detail; the description's mention of propertyId largely restates the schema. Baseline 3 is appropriate since the schema carries the 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?

The description gives a specific verb+resource ('Edit an image') plus a concrete example instruction, so an agent can tell it apart from narrower siblings like pedra_enhance or pedra_remove_object. It does not, however, explicitly contrast itself with those preset-style editing tools, so it stops 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?

Usage is implied (free-form natural-language editing) and it usefully explains when to pass propertyId versus not. But it never names alternatives such as the preset edits (pedra_enhance, pedra_furnish, pedra_remove_object), leaving the agent to infer which editing tool to pick.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false), so the bar is lower. The description adds useful behavior beyond them: it explains what is produced (an emptied image URL) and that passing propertyId persists the result into a property gallery rather than only returning a URL. It does not contradict the non-destructive hint since the source image is only edited.

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 with zero waste; the core action is front-loaded and the persistence nuance follows.

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, and the description compensates by stating the return value (emptied image URL) plus the gallery-save variant. Combined with fully documented parameters, an agent has nearly everything needed, with only when-to-use guidance 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 the schema already documents all four parameters in more detail than the description. The description's propertyId note merely restates the schema's save-into-gallery behavior, adding no syntax or default information beyond it.

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, leaving an empty space') and the outcome. It is clearly distinct from siblings like pedra_furnish and pedra_remove_object, though it never names an alternative explicitly to sharpen that 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?

Gives implied context via the imageUrl/propertyId workflow, but never says when to choose this over pedra_remove_object or pedra_furnish, nor any prerequisites. Usage is inferable rather than stated.

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

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

Annotations declare a non-read-only, non-destructive, open-world operation, and the description usefully adds the return value (enhanced image URL) and the important side effect that passing propertyId persists the result into a property gallery — a meaningful behavioral detail not derivable from the annotations. It omits cost/credit consumption, which matters given the 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?

Three short sentences with no filler, front-loading the core action before the return-value and propertyId notes. Size is well matched to a single-purpose image tool, though the propertyId sentence is largely a paraphrase of the schema field.

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 5-parameter tool with full schema coverage, no output schema, and safety annotations already present, the description covers the action, the return, and the persistence option adequately; an agent could call it correctly. Missing only operational context such as cost and expected processing time.

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 per-parameter docs are unusually detailed, so the schema does the heavy lifting. The description only restates the propertyId behavior ('save the result into that property's gallery instead of only returning a URL'), adding no syntax or format information beyond it; 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?

Names a specific verb and resource (enhance a real-estate photo) and enumerates the effect (lighting, color, sharpness), which is more than a restatement of the name. It does not, however, distinguish itself from the very close sibling pedra_enhance_and_correct_perspective, so an agent cannot tell from this text alone which of the two 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?

The description states what happens when propertyId is passed, but never states when to use this tool rather than a sibling (e.g. pedra_enhance_and_correct_perspective when perspective also needs fixing, or pedra_edit_via_prompt for arbitrary edits). No exclusions, no prerequisites, no stated ceiling on what 'enhance' covers.

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-destructive, open-world operation, and the description adds real behavioral context beyond that: the save-into-gallery side effect of propertyId, the fact that an already-present photo keeps its name, and that a URL is returned otherwise. It does not mention cost/credit consumption or latency for this enhancement, which would round it 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?

Two short sentences, front-loaded with the operation and output, then the optional persistence behavior. Nothing is wasted or buried.

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 states the return value (corrected image URL) and covers the meaningful side effect of propertyId. It does not address credit cost or failure modes, which matters given sibling pedra_credits, so it falls short of fully 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%, so the schema already documents imageUrl, propertyId, name, and both preserve flags in detail. The description only restates the propertyId behavior; it adds no syntax or format detail the schema lacks. Baseline 3 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?

States a specific verb (enhance) plus a second concrete operation (correct vertical/horizontal perspective), with a parenthetical explaining what that means for the output. An agent can distinguish it from the sibling pedra_enhance, which only enhances.

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?

Implies usage through 'straighten walls and lines' and explains the propertyId save-vs-return decision, but never states when to pick this over pedra_enhance or other editing siblings (pedra_sky_blue, pedra_remove_object, etc.). No explicit when/when-not guidance or prerequisites such as credit cost.

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 safety is partly covered. The description adds real side-effect detail beyond them: the result is saved into the property's gallery 'visible and editable from the app' when propertyId is set, versus only returning a URL otherwise. It does not mention credit cost or latency, which pedra_credits hints are relevant.

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, front-loaded with the core action and followed by the single most consequential option. 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?

With no output schema, the description correctly states the return value (staged image URL) and covers the persistence nuance. For a 6-parameter generative tool, the remaining gap is cost/async expectations, but nothing needed 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 every parameter is already documented with format, defaults, and examples (e.g. preserveAspectRatio's cropping behavior, imageUrl's accepted forms). The description's propertyId sentence restates the schema rather than adding new semantics, so the baseline 3 is 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?

States a specific verb and resource: 'Virtually stage (furnish) a room with AI-generated furniture,' plus the return artifact ('Returns the staged image URL'). It is clearly distinguishable from siblings like pedra_empty_room (the inverse operation) and pedra_renovation.

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 one conditional usage rule (pass propertyId to persist into a gallery rather than only getting a URL), which is useful, but offers no guidance on when to choose this over adjacent tools like pedra_renovation, pedra_edit_via_prompt, or pedra_enhance. Usage is implied rather than framed against 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 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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, and the description adds meaningful context beyond them: results can either be returned as a URL or persisted into a property gallery, and gallery-saved output is "visible and editable from the app." It does not mention credit cost or whether the source image is left untouched, which keeps it short of 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 sentences, zero filler, with the core action and return value front-loaded and the optional persistence behavior second. 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?

No output schema exists, and the description covers the return value (cleaned image URL). Combined with the fully documented schema, an agent has enough to invoke it correctly; only the cost/rate-limit dimension is absent, which is minor.

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 each parameter is already documented in the schema, so the baseline is 3. The description restates the propertyId behavior but adds no syntax or format meaning not already present in the schema fields.

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 an object from an image") plus the required mechanism ("using a mask") and the primary outcome ("Returns the cleaned image URL"), which cleanly separates it from prompt-based siblings like pedra_edit_via_prompt or pedra_enhance.

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 explains the propertyId save-vs-return choice, which is real usage guidance, but never states when to prefer this tool over alternatives such as pedra_edit_via_prompt or pedra_blur, nor any prerequisites beyond what the schema already says.

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, non-destructive, open-world operation. The description notes that a result URL is returned and that passing propertyId persists the result into a gallery, which is a meaningful side-effect distinction for a mutation. However, that same side-effect is fully spelled out in the propertyId schema field, so the description adds little beyond structured data; no coverage of latency, cost, or failure 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?

Three short sentences, front-loaded with the core action and then the propertyId conditional, with no filler. Slightly tighter than ideal only because the propertyId sentence duplicates the schema field almost verbatim.

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 states the return value ('the renovated image URL'), and 100% schema coverage handles parameters. The main omission is tool-selection context against closely related siblings, but for a single-purpose image-generation call the definition is nearly callable as-is.

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 all seven parameters, including the notable furnish and preserveAspectRatio semantics. The description only echoes 'optionally furnished' and the propertyId effect, adding no syntax, defaults, or enum meaning beyond what the fields provide. Baseline 3 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?

States a specific verb and resource ('Renovate a space') plus the scope of the operation (walls, floors, finishes), so an agent knows it produces a renovated image. It does not distinguish itself from siblings that overlap heavily, notably pedra_furnish and pedra_empty_room, whose functions are partially absorbed by the 'furnish' parameter here.

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 guidance and names no alternatives, despite several siblings (pedra_furnish, pedra_empty_room, pedra_edit_via_prompt) that could plausibly be chosen instead. The only conditional given is about propertyId, which is a parameter behavior, not tool selection guidance.

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 mark this as a non-readOnly, non-destructive, open-world operation, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses the return value ('image URL with the new sky') and the side effect of propertyId saving the result into a gallery rather than only returning a URL. It does not mention credit consumption or processing time, which keeps it short of 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 sentences, zero padding, and the core purpose is front-loaded before the return-value and persistence details. Every clause carries information the 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?

With no output schema, the description correctly states what is returned, and the rich input schema covers parameters and input guidance. For a mutation tool it is nearly complete, though it could mention credit cost (pedra_credits is a sibling) and that skyStyle values are constrained.

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 every parameter in detail. The description's note about propertyId saving to the gallery largely restates what the propertyId schema description already says, so it adds little beyond the structured fields — the baseline 3 for full coverage 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?

The description states a concrete verb and resource: replace a dull/overcast sky with a clear blue one. This is unambiguous and clearly distinguishable from siblings such as pedra_enhance, pedra_furnish, or pedra_edit_via_prompt, since it names a specific transformation target (the sky).

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 implies the triggering condition ('dull or overcast sky') but never states when to choose this over alternatives like pedra_edit_via_prompt or pedra_enhance, nor any exclusions (e.g. indoor shots, already-blue skies). Usage is inferable but never 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?

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.