Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Pedra MCP Server How many Pedra credits do I have left?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Official Model Context Protocol server for the Pedra API — use Pedra's AI real-estate photo editing (virtual staging, renovation, room emptying, enhancement, sky replacement, object removal/blur, and property videos) directly from Claude, ChatGPT, Cursor, and any other MCP client.
It exposes one tool per API endpoint. Each tool is a single blocking call that returns the final asset URL(s) — there are no job IDs to poll.
You need a Pedra API key — get one from your Pedra account. The server reads it from the PEDRA_API_KEY environment variable.
The server runs over stdio and is published to npm, so most clients just run it with npx — no global install needed.
Download the latest pedra-mcp.mcpb from Releases and double-click it (or drag it into Claude Desktop → Settings → Extensions). Claude installs the bundled server and prompts for your PEDRA_API_KEY — no JSON editing.
Or add this to your claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"pedra": {
"command": "npx",
"args": ["-y", "@pedra-ai/mcp"],
"env": { "PEDRA_API_KEY": "your-api-key" }
}
}
}In ~/.cursor/mcp.json (or .cursor/mcp.json in a project):
{
"mcpServers": {
"pedra": {
"command": "npx",
"args": ["-y", "@pedra-ai/mcp"],
"env": { "PEDRA_API_KEY": "your-api-key" }
}
}
}Run the binary directly with the key in the environment:
PEDRA_API_KEY=your-api-key npx -y @pedra-ai/mcpOr install it:
npm install -g @pedra-ai/mcp
PEDRA_API_KEY=your-api-key pedra-mcpYou can also install and configure Pedra automatically via Smithery:
npx -y @smithery/cli install @pedra-ai/mcp --client claude(swap claude for cursor, windsurf, etc.) Smithery prompts for your PEDRA_API_KEY and writes the client config for you.
Related MCP server: Rendobar MCP Server
Tool | Endpoint | What it does |
|
| Improve lighting, color, sharpness |
|
| Enhance + straighten perspective |
|
| Remove all furniture/objects |
|
| Virtually stage a room |
|
| Renovate walls/floors/finishes |
|
| Edit from a natural-language prompt |
|
| Replace a dull sky with clear blue |
|
| Remove an object using a mask |
|
| Blur faces, license plates, etc. |
|
| Render a property video from images |
|
| Edit a video without re-rendering unchanged clips |
|
| Write a voiceover script from property photos |
|
| Turn a script into a voiceover audio track |
|
| List background-music tracks + voice languages |
|
| List the account's properties |
|
| List a property's photos as URLs |
|
| Create a property |
|
| Add photos to a property by URL |
|
| Read plan + remaining credits |
|
| Thumbs up/down + optional credit-back |
Most image tools take an imageUrl plus a few optional parameters; see each tool's input schema in your MCP client. The imageUrl (and maskUrl, and each create_video frame) accepts any of:
a public https:// URL,
a data: URI, or
an absolute path to a local image file — the server reads it off disk and inlines it as base64 for you, so you can point a tool at a file you just dragged in without hosting it first (.jpg, .jpeg, .png, .webp, .gif, .bmp, .tif/.tiff, .heic/.heif, .avif; up to 40 MB).
Note: an image pasted into the chat is not a file path, so it can't be forwarded to the tool — drag in a file, or save the paste and pass its path.
Example prompts once connected:
"Use Pedra to virtually stage https://example.com/empty-living-room.jpg as a minimalist living room."
"Virtually stage /Users/me/Desktop/empty-living-room.jpg as a minimalist living room."
"How many Pedra credits do I have left?"
This server is a thin wrapper over @pedra-ai/sdk, which encodes the API's contract details:
Synchronous by design. Every endpoint blocks and returns the final URL(s) in the response body. Even pedra_create_video polls server-side and returns the finished videoUrl inline (it can take up to ~10 minutes; the API keeps the connection alive with a heartbeat).
Errors are tool errors. The API's 4xx responses (insufficient credits, bad image, …) come back as MCP tool errors with a readable message, not crashes.
This server sends the image/video URLs and parameters you pass to the Pedra API to perform the requested edit, authenticated with your PEDRA_API_KEY. It stores no data itself. Data collection, usage, storage, retention, third-party sharing, and contact information are covered by Pedra's privacy policy: https://pedra.ai/privacy.
MIT © Pedra
Add photos to a property BY URL — the server fetches each URL and stores it, so any public https image URL (or a small data: URI) works. Returns the stored img.pedra.ai URLs. For local files on the user's device, direct them to the property's appUrl instead (chat can't transfer large local files).
| Name | Required | Description | Default |
|---|---|---|---|
| imageUrls | Yes | Up to 20 image URLs to fetch and add to the property. | |
| propertyId | Yes | Target property id (from pedra_list_properties or pedra_create_property). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explains the server fetches and stores URLs, and returns stored URLs. The description adds behavioral context beyond annotations (readOnlyHint false, destructiveHint false, openWorldHint true), though it doesn't detail error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and method, no wasted words. Every sentence provides critical 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?
Given only 2 parameters and no output schema, the description covers purpose, method, constraints, and alternative for local files. Complete for an agent to correctly invoke the 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?
Adds value beyond schema by stating imageUrls can be public https or data: URI, and propertyId is from other tools. Schema coverage is 100%, but description enriches understanding with format and source constraints.
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 starts with 'Add photos to a property BY URL', clearly stating the verb and resource. It distinguishes from sibling tools by specifying the method and excluding local files.
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 states when to use (via URL) and when not to (local files, directing to appUrl). Provides clear context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Blur objects in an image (e.g. faces, license plates) for privacy. Returns the blurred image URL.
| Name | Required | Description | Default |
|---|---|---|---|
| imageUrl | Yes | Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically). | |
| objectsToBlur | Yes | Labels/regions to blur, e.g. ["faces", "license plates"]. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool returns a URL of the blurred image, which implies the original is preserved. Annotations already indicate non-destructive (destructiveHint=false) and open world. The description adds return format context but does not reveal potential side effects or limitations.
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 extremely concise: two sentences that cover purpose, examples, and return. No wasted words.
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, the description covers the main points: what it does, examples, and what is returned. It lacks error handling or performance notes but is sufficiently complete for most use cases.
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%, and the schema provides detailed descriptions for both parameters. The description adds example values ('faces', 'license plates') but does not significantly extend meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'blur', the resource 'objects in an image', and the purpose 'for privacy'. Examples like 'faces, license plates' provide concrete context. However, it does not explicitly differentiate from sibling tools like pedra_remove_object.
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 guidance is provided on when to use this tool versus alternatives (e.g., pedra_remove_object for complete removal). The description lacks any usage context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Pedra property. Returns its propertyId and an appUrl. To add brand-new local photos (which can't be uploaded through chat), give the user the appUrl to open the property in Pedra and drop their photos in, then use pedra_list_property_images.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Property name, e.g. the listing address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutation (readOnlyHint=false) but no destruction (destructiveHint=false) and openWorldHint=true. The description adds context by revealing that chat cannot upload photos, so the appUrl is essential, and that the tool returns both propertyId and appUrl. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with only two sentences, no unnecessary words, and the primary purpose is front-loaded in the first sentence.
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 one parameter, no output schema, and sufficient annotations, the description covers the key outputs and a follow-up workflow hint. It is adequately 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?
The input schema already provides a description for the single parameter 'name' with 100% coverage. The tool description does not add further meaning or usage details for this parameter, so a baseline score of 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?
The description clearly states the verb 'Create' and the resource 'Pedra property', and distinguishes itself from sibling tools like pedra_add_images_to_property and pedra_list_properties by specifying the return values (propertyId and appUrl).
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 provides workflow guidance by mentioning that the appUrl is needed for adding local photos and suggests using pedra_list_property_images after creation. However, it lacks explicit when-not-to-use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a property video from a list of images. Blocks server-side until the video is rendered (up to ~10 min) and returns the finished video URL inline.
| Name | Required | Description | Default |
|---|---|---|---|
| music | No | ||
| voice | No | ||
| images | Yes | Ordered list of images that make up the video. | |
| branding | No | ||
| isVertical | No | Force a vertical (9:16) video. | |
| endingTitle | No | ||
| endingSubtitle | No | ||
| propertyCharacteristics | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) are present. The description adds the critical behavioral trait of blocking for up to 10 minutes and returning the URL inline. However, it does not disclose other traits like error handling or idempotency, leaving gaps despite annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the purpose and key behavior. Every word adds value; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, nested objects, no output schema), the description is inadequate. It covers core functionality but misses usage details, error scenarios, and return format specifics beyond 'URL inline'. Expected more for a creation 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 low (25%) and the description adds no meaning to the many nested parameters. It only mentions 'list of images', ignoring music, voice, branding, etc. The agent gets minimal help from the description beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the resource 'property video' from a list of images. It distinguishes from sibling tools like pedra_edit_via_prompt and pedra_update_video by implying this is the primary creation tool.
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 initial video creation from images but does not explicitly state when to use alternatives or provide exclusions. Context from siblings helps, but explicit guidance is lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the account's plan and remaining credits. Never deducts credits.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Edit an image from a natural-language instruction (e.g. "paint the walls sage green"). Returns the edited image URL.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Natural-language description of the edit to apply. | |
| imageUrl | Yes | Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description notes the return value (edited image URL) and implies a mutation (edit). Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds minimal behavioral context. No contradictions.
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, well-structured sentence that includes an example. Every word serves a purpose; no fluff.
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, the description adequately explains input and output. It could mention constraints (e.g., supported edits or image format) but is sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well described in the schema. The description repeats some info (prompt example) but does not add meaning beyond the schema.
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 ('Edit'), a resource ('image'), and a mechanism ('natural-language instruction'), with a concrete example. It clearly distinguishes from sibling tools like pedra_remove_object (targeted removal) and pedra_blur (specific effect) by conveying a general-purpose editing capability.
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 guidance on when to use this tool versus alternatives. Siblings like pedra_enhance, pedra_remove_object, or pedra_sky_blue offer more specific operations, but the description does not mention these or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove all furniture and objects from a room, leaving an empty space. Returns the emptied image URL.
| Name | Required | Description | Default |
|---|---|---|---|
| imageUrl | Yes | Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that the tool empties the room and returns a URL, providing additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and output, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description fully covers what an agent needs: action, resource, and return value.
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% for the single parameter. The description does not add any meaning beyond what the schema already provides, so baseline score 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?
The description clearly states the action (remove all furniture and objects), the resource (a room), and the output (emptied image URL). It distinguishes from siblings like pedra_remove_object and pedra_furnish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to empty a room) but does not explicitly state when not to use or list alternatives. Sibling names like pedra_remove_object provide context, but the description itself lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enhance a real-estate photo: improve lighting, color, and sharpness. Returns the enhanced image URL.
| Name | Required | Description | Default |
|---|---|---|---|
| imageUrl | Yes | Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically). | |
| preserveOriginalFraming | No | Preserve the original framing/aspect ratio/resolution exactly (for verification verticals where the output must legally represent the captured photo). Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-destructive, open-world. Description adds that it returns a URL but doesn't elaborate on side effects, rate limits, or auth needs. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences, front-loaded with key information. No fluff.
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, parameters, and output adequately. Lacks behavior details but sufficient for a simple enhancement tool. With no output schema, describing return format could improve.
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%, with clear descriptions for both parameters. Description does not add extra meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'enhance' and resource 'real-estate photo', listing specific improvements (lighting, color, sharpness) and output. Distinguishes it from siblings like pedra_enhance_and_correct_perspective.
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 for enhancing photos, but no explicit guidance on when to use vs. alternatives like pedra_enhance_and_correct_perspective or pedra_edit_via_prompt. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enhance a photo and correct vertical/horizontal perspective (straighten walls and lines). Returns the corrected image URL.
| Name | Required | Description | Default |
|---|---|---|---|
| imageUrl | Yes | Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically). | |
| preserveOriginalFraming | No | Preserve the original framing/aspect ratio/resolution exactly (for verification verticals where the output must legally represent the captured photo). Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-destructive and read-write behavior. The description adds that it 'enhances' and 'corrects perspective' but does not elaborate on what 'enhance' entails (e.g., color adjustment, sharpness). The return of a corrected image URL is stated, but no details on side effects or persistence. The description adds minimal value beyond 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 efficiently convey the tool's action and output. No superfluous words, front-loaded with the primary function. 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 tool with only two parameters and no output schema, the description is adequate but lacks depth. It does not explain what 'enhance' means operationally or provide examples of typical use cases. The return value is mentioned briefly (URL), but more detail (e.g., format, size) would improve completeness.
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%, and the description does not add meaning beyond the schema's parameter descriptions. The 'imageUrl' parameter is already well-described in the schema; 'preserveOriginalFraming' is also explained. The description simply restates the tool's purpose without enriching parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('enhance', 'correct perspective') and identifies the resource ('photo'). It clearly states the output (corrected image URL) and distinguishes from sibling tools like pedra_enhance (which only enhances) and pedra_edit_via_prompt (which is more generic).
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 the tool is for photos needing perspective correction and enhancement, but it does not explicitly state when to use this tool versus other editing tools (e.g., pedra_enhance for pure enhancement) or when not to use it. No alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit thumbs up/down feedback on a generated image, with an optional credit-back on a thumbs-down (subject to the API's eligibility rules).
| Name | Required | Description | Default |
|---|---|---|---|
| vote | No | Thumbs up/down. An empty string clears a previous vote. | |
| comment | No | ||
| imageId | No | Explicit image id. One of imageUrl/imageId is required. | |
| imageUrl | No | The generated image URL to vote on (id is parsed from it). | |
| creditBack | No | Request a credit refund (only honored on a thumbs-down). |
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.
Virtually stage (furnish) a room with AI-generated furniture. Returns the staged image URL.
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | e.g. "Minimalist", "Scandinavian", "Modern". | |
| imageUrl | Yes | Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically). | |
| roomType | No | e.g. "Living room", "Bedroom", "Kitchen". Auto-detected if omitted. | |
| creativity | No | Strength of the AI transformation. Defaults to "Medium". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description notes AI generation, aligning with openWorldHint=true. It does not contradict annotations, but lacks details on what happens to the original image, auth needs, or rate limits.
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 brief sentences, no fluff, front-loaded with action and output.
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 basic action and return type. Missing guidance on optional parameters, expected output resolution, or processing time. Adequate but not thorough.
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 schema already describes all parameters. The description adds no extra meaning beyond the schema.
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 it virtually stages a room with AI-generated furniture and returns the staged image URL. It distinguishes the tool from siblings like pedra_empty_room, but does not explicitly name alternatives.
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 guidance on when to use this tool versus alternatives like pedra_empty_room or pedra_renovation. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a voiceover from a script via text-to-speech. Returns an audioId — pass it to pedra_create_video / pedra_update_video as voice.audioId to attach the narration (with synced subtitles).
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The script to narrate (max 1000 characters). | |
| language | No | Voice language, e.g. "English", "Español". Defaults to English. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive action ('readOnlyHint': false, 'destructiveHint': false). The description adds valuable context: returns an audioId, attaches narration with synced subtitles. It does not detail potential side effects like cost or limits, but the added usage info compensates.
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 wasted words. First sentence declares the action and return; second explains integration. Front-loaded with critical 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?
The tool has only two parameters and no output schema. The description explains the return value and its usage, covering the essential context. It does not mention error handling or limitations beyond the schema's max characters, but it is complete for its 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 coverage is 100%, so the description is not required to explain parameters. It adds no extra meaning beyond what the schema already provides (e.g., text max length, language default). Baseline score of 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?
The description uses a specific verb ('render') and resource ('voiceover from script'), clearly distinguishing it from the sibling 'pedra_generate_voice_script'. It states the return value (audioId) and how to use it, leaving no ambiguity.
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 explains when to use the tool (render voiceover from script) and what to do with the output (pass to video tools as voice.audioId with synced subtitles). It does not explicitly say when not to use it or list alternatives, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a short voiceover script from property photos (and optional facts). GPT-4o vision reads the images so the script reflects what's actually shown. Returns the script text — pass it to pedra_generate_voice.
| Name | Required | Description | Default |
|---|---|---|---|
| images | No | Photos to base the script on (URLs or { imageUrl }). | |
| language | No | Script language, e.g. "English", "Español". Defaults to English. | |
| propertyCharacteristics | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readonly, non-destructive, and open-world behavior. The description adds that GPT-4o vision reads images and that the script reflects actual content, but does not disclose additional traits like token limits, script length constraints, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose. Every sentence adds value: defines the tool, explains the AI capability, and provides a workflow hint. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains input (photos and optional facts), process (GPT-4o vision), and output (script text) along with the next step. For a simple tool with no required parameters and no output schema, it covers the essential aspects, though missing error handling or limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 67% schema coverage, the description adds value by clarifying that images are read by vision AI and that propertyCharacteristics are 'optional facts'. It also provides a default for language. The propertyCharacteristics parameter's purpose is hinted but could be more explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'write' and the resource 'short voiceover script', and specifies that it uses property photos and optional facts. It distinguishes from sibling 'pedra_generate_voice' by noting the script output is passed to that tool.
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 a workflow by instructing to pass the result to pedra_generate_voice, but does not explicitly state when to use this tool versus alternatives or when not to use it. However, the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's Pedra properties (id, name, photo count, and an appUrl to open each in Pedra). Use this to find photos already in the account — e.g. to build a video from a listing's photos.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
List a property's photos as img.pedra.ai URLs, ready to pass straight to pedra_create_video or the image-editing tools. Get the propertyId from pedra_list_properties.
| Name | Required | Description | Default |
|---|---|---|---|
| propertyId | Yes | The property's id (from pedra_list_properties). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, and the description reinforces this by describing a read-only list operation. It adds value by specifying the URL format and the tool's role as a data source for other tools, which annotations do not cover.
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 wasted words. The purpose is front-loaded, and each sentence serves a clear function: stating the tool's action and providing a usage hint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single required parameter and the presence of readOnly annotations, the description sufficiently covers the tool's behavior and return format. No output schema exists, but the description compensates by explaining that the output is a list of URLs.
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. The description mentions propertyId and its source but does not add significant details beyond the schema's 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 specifies a concrete verb ('List'), a clear resource ('a property's photos'), and the output format ('img.pedra.ai URLs'). It also explicitly states downstream compatibility with specific sibling tools, distinguishing it well.
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 tells users exactly when to use it: to obtain photos for video creation or image editing. It also explains how to get the required propertyId from pedra_list_properties. While it does not explicitly state when not to use it, the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the background-music catalog: valid music.track values (genre keys) and the voice languages accepted by the voiceover tools. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 lists specific values and is read-only, providing complete behavioral context 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?
The description is a single, well-structured sentence that front-loads the action and specifies the output. No unnecessary words.
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 tool with no parameters and no output schema, the description completely explains what the tool provides (valid music.track values and voice languages), which is sufficient for an agent to use 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?
There are no parameters, and the schema coverage is 100% (trivially). The description adds meaning by explaining what the tool returns without needing parameters, meeting the baseline of 4 for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists the background-music catalog, specifically valid `music.track` values (genre keys) and voice languages accepted by voiceover tools. This distinguishes it from siblings like pedra_generate_voice which are about generating voice.
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 it should be used to retrieve valid options for music and voice languages before using voiceover tools, but does not explicitly state when to use or when not to use. It gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an object from an image using a mask. Returns the cleaned image URL.
| Name | Required | Description | Default |
|---|---|---|---|
| maskUrl | Yes | Mask image marking the region to remove: a public https:// URL, a data: URI, or a local file path. | |
| imageUrl | Yes | Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, which are consistent with the description. The description adds the output format (URL), but lacks details on potential side effects, error handling, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently conveys the core functionality without any 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?
Given the tool's simplicity (2 required parameters, no output schema), the description covers the essential input and output. However, it could mention image format limitations or mask requirements.
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%, with both parameters fully described in the schema. The description does not add additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove an object'), the method ('using a mask'), and the output ('Returns the cleaned image URL'). It effectively distinguishes from sibling tools like pedra_blur and pedra_sky_blue.
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 (when you want to remove an object with a mask) but does not explicitly state when to use this tool versus alternatives or provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renovate a space (walls, floors, finishes), optionally furnished. Returns the renovated image URL.
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | Renovation style. | |
| furnish | No | Whether the renovated room should be furnished (true → with furniture, false → empty). | |
| imageUrl | Yes | Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically). | |
| roomType | No | Room type. Auto-detected if omitted. | |
| creativity | No | Strength of the AI transformation. Defaults to "Medium". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds that it returns a URL, which is consistent. No additional behavioral traits (e.g., cost, side effects) are disclosed, but there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that concisely states the action, scope, optionality, and return value. No unnecessary words.
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 5 parameters, 1 required, and no output schema, the description is minimal. It covers the core purpose but lacks details on style options or behavior. Given the well-described schema, it is adequate but could be more helpful.
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 baseline is 3. The description mentions 'optionally furnished' which relates to the furnish parameter, but does not add meaning beyond what the schema already provides for other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Renovate') and specifies the resource ('a space') with details on what is renovated ('walls, floors, finishes'). It also mentions optional furnishing and the return value. This clearly distinguishes it from sibling tools like pedra_furnish or pedra_empty_room.
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 use when you want to renovate a space, but does not explicitly state when to use this tool versus alternatives like pedra_furnish or pedra_edit_via_prompt. While the purpose is clear, no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a dull or overcast sky with a clear blue one. Returns the image URL with the new sky.
| Name | Required | Description | Default |
|---|---|---|---|
| imageUrl | Yes | Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically). | |
| skyStyle | No | Optional named sky style. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide non-read-only and open-world hints. The description adds that the tool returns a new image URL, which is helpful, but does not disclose other behaviors like auth requirements, rate limits, or side effects beyond what annotations imply. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two short sentences. The first sentence states the purpose, and the second states the return value. No wasted words.
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 two parameters and no output schema, the description covers purpose and return value adequately. It could mention that skyStyle is optional or provide examples, but overall it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters with descriptions (100% coverage), so the description adds no additional semantic value. 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?
The description clearly states the tool's action ('Replace a dull or overcast sky with a clear blue one') and specifies the resource (sky). It distinguishes itself from sibling tools like pedra_remove_object and pedra_enhance by focusing on a specific transformation.
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 indicates when to use the tool (dull or overcast sky) but does not explicitly state when not to use it or mention alternatives. The context is clear but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing video (by videoId) without re-rendering unchanged clips — only new/changed photos re-animate and cost credits; reordering, music, voice, branding and text re-stitch for free. Omit images to change only audio/text/branding while keeping the current timeline. Omit music/voice/branding/ending text to leave them unchanged. Blocks until rendered and returns the new video URL.
| Name | Required | Description | Default |
|---|---|---|---|
| music | No | ||
| voice | No | ||
| images | No | Full ordered image list to rebuild the timeline; matching photo+effect clips are reused. Omit to edit only audio/text and keep the current timeline. | |
| videoId | Yes | Id of the video to edit (from pedra_create_video). | |
| branding | No | ||
| isVertical | No | Force a vertical (9:16) video (only when images are sent). | |
| endingTitle | No | ||
| endingSubtitle | No | ||
| propertyCharacteristics | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool blocks until rendered and returns the new video URL, adding value beyond annotations. It also mentions credit costs for new/changed photos. While annotations already indicate mutation (readOnlyHint=false) and no destruction (destructiveHint=false), the description enriches with synchronous behavior and cost implications.
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 concise with no redundant sentences. It front-loads the primary purpose ('Edit an existing video by videoId without re-rendering unchanged clips'), then efficiently covers cost, optional omissions, and behavior. Every sentence adds 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?
Despite no output schema, the description states it returns a URL. It covers core usage patterns but lacks details on some parameters (e.g., propertyCharacteristics, isVertical) and does not explain error cases or pagination. For a tool with 9 parameters and nested objects, it provides a good overview but is not exhaustive.
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 low (33%), so the description compensates by explaining high-level semantics: omitting images leaves timeline unchanged, omitting music/voice/branding/ending text leaves them unchanged, and images parameter is the full ordered list. This contextualizes parameters effectively, though some parameters like 'isVertical' and 'propertyCharacteristics' are not addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool edits an existing video by videoId, emphasizing it avoids re-rendering unchanged clips. It distinguishes from create_video by specifying that only new/changed photos cost credits, while reordering, music, voice, branding, and text re-stitch for free. This gives a precise verb-resource-scope and differentiates from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to omit fields (e.g., 'omit images to change only audio/text/branding while keeping the current timeline'), which is helpful. However, it does not contrast directly with the sibling 'pedra_edit_via_prompt' or explicitly state prerequisites (e.g., video must exist from pedra_create_video). The context is clear but lacks alternative choices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.0pedra_add_images_to_projectpedra_add_images_to_propertypedra_create_projectpedra_create_propertypedra_list_project_imagespedra_list_projectspedra_list_propertiespedra_list_property_imagesv0.3.0pedra_add_images_to_projectpedra_create_projectpedra_create_video4 fields changedInput schema / properties / music / properties / track / descriptionAdded value: +"Genre key from pedra_music_library (e.g. acoustic, chill, cinematic, electronic, upbeat)."Input schema / properties / voice / properties / audioIdAdded value: +{
+ "description": "Id of a voiceover from pedra_generate_voice. Drives the narration and its synced subtitles.",
+ "type": "string"
+}Input schema / properties / voice / properties / audioUrl / descriptionAdded value: +"Legacy alias for audioId."Input schema / properties / voice / properties / showSubtitlesAdded value: +{
+ "description": "Burn in word-synced subtitles. Defaults to true.",
+ "type": "boolean"
+}pedra_generate_voicepedra_generate_voice_scriptpedra_list_project_imagespedra_list_projectspedra_music_librarypedra_update_videov0.1.2pedra_blur1 field changedInput schema / properties / imageUrl / descriptionPrevious value: -"URL (or data: URL) of the source image."New value: +"Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically)."pedra_create_video1 field changedInput schema / properties / images / items / properties / imageUrl / descriptionPrevious value: -"URL (or data: URL) of the source image."New value: +"Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically)."pedra_edit_via_prompt1 field changedInput schema / properties / imageUrl / descriptionPrevious value: -"URL (or data: URL) of the source image."New value: +"Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically)."pedra_empty_room1 field changedInput schema / properties / imageUrl / descriptionPrevious value: -"URL (or data: URL) of the source image."New value: +"Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically)."pedra_enhance1 field changedInput schema / properties / imageUrl / descriptionPrevious value: -"URL (or data: URL) of the source image."New value: +"Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically)."pedra_enhance_and_correct_perspective1 field changedInput schema / properties / imageUrl / descriptionPrevious value: -"URL (or data: URL) of the source image."New value: +"Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically)."pedra_furnish1 field changedInput schema / properties / imageUrl / descriptionPrevious value: -"URL (or data: URL) of the source image."New value: +"Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically)."pedra_remove_object2 fields changedInput schema / properties / imageUrl / descriptionPrevious value: -"URL (or data: URL) of the source image."New value: +"Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically)."Input schema / properties / maskUrl / descriptionPrevious value: -"URL of the mask image marking the region to remove."New value: +"Mask image marking the region to remove: a public https:// URL, a data: URI, or a local file path."pedra_renovation1 field changedInput schema / properties / imageUrl / descriptionPrevious value: -"URL (or data: URL) of the source image."New value: +"Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically)."pedra_sky_blue1 field changedInput schema / properties / imageUrl / descriptionPrevious value: -"URL (or data: URL) of the source image."New value: +"Source image: a public https:// URL, a data: URI, or an absolute path to a local image file (the file is read and inlined automatically)."v0.1.0pedra_blurpedra_create_videopedra_creditspedra_edit_via_promptpedra_empty_roompedra_enhancepedra_enhance_and_correct_perspectivepedra_feedbackpedra_furnishpedra_remove_objectpedra_renovationpedra_sky_blueScored across 20 tools
Each tool has a clearly distinct purpose, from image editing (blur, empty, enhance, etc.) to property management and video creation. Descriptions are detailed and leave no ambiguity about what each tool does.
All tools follow the pattern 'pedra_verb_noun_or_phrase' with consistent snake_case. Examples like pedra_create_property, pedra_edit_via_prompt, and pedra_enhance_and_correct_perspective show a predictable structure.
With 20 tools, the server covers a broad range of real estate photo and video editing tasks without being overwhelming. Each tool serves a specific function, and the count is well-scoped for its domain.
The tool surface covers core workflows (property creation, image editing, video production, voiceover) well. However, it lacks delete operations for properties, images, or videos, which are minor gaps in an otherwise comprehensive set.
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Official MCP server for subfeed.app — the cloud for agents. 15+ tools for AI agents to register, build, and deploy other agents. Zero human required. Start here: subfeed.app/skill.md
Official MCP server for Lovable, the AI-powered full-stack app builder.
MCP server for NanoBanana AI image generation and editing
