Meta Ads MCP server for Facebook and Instagram ads in Claude, ChatGPT, Codex, Cursor and any MCP client: reports with breakdowns, campaigns, ad sets, ads, creatives, audiences and catalogs, with approval on every write. Hosted by Markifact, OAuth login, nothing to install locally.
Glama couldn't complete the latest health check. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 10 tools
Most tools have clearly distinct purposes and a well-defined workflow (find_operations → get_operation_inputs → run_operation/run_write_operation). However, prepare_media_upload and upload_media overlap in intent, and get_file_url vs read_file could be confused without careful reading. Overall, slight ambiguity in file/media handling.
All tools use consistent snake_case with a verb_noun pattern (find_operations, get_operation_inputs, run_operation, etc.). No mixing of conventions. Highly predictable and readable.
10 tools is appropriate for a gateway to an operation-based platform. Each tool covers a distinct aspect (discovery, schema, execution, files, connections, feedback). No redundant or missing major pieces.
The surface covers discovery, schema retrieval, read/write execution, file inspection and URLs, connections, media upload, and feedback reporting. Minor gap: no explicit tool to list all operations without a search, and file management lacks deletion, but core workflows are covered.
Search for available Markifact operations that can be executed by the authenticated user.
Workflow: find_operations → get_operation_inputs → run_operation (read-only) or run_write_operation (when requires_approval: true). After selecting an operation_id, always call get_operation_inputs next. Never call run_operation / run_write_operation without first inspecting the schema via get_operation_inputs. Input shapes, nested objects, and field names vary per operation and cannot be guessed. Returned operation IDs are registry-backed Markifact operation IDs, not arbitrary action names.
Returns JSON with matching operations containing operation_id, description, and app metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return (default 5). | |
| query | No | Keyword search over operation ids and descriptions. Use two to four words: the app name plus the entity or action, e.g. "meta ads list ads", "gtm create tag". Long sentences match too many operations. If the expected operation is not in the results, search again with a shorter query or a higher limit before concluding it does not exist. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the IDs are registry-backed rather than arbitrary action names, and the mandatory schema-inspection step before execution. It does not discuss pagination or result-ordering behavior, so it stops 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?
Purpose is front-loaded and the workflow/constraint sentences each carry distinct operational value. Slightly dense with several imperative lines, but nothing is redundant with 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?
An output schema exists, so return fields need not be enumerated, yet the description still names the key returned fields (operation_id, description, app metadata). Combined with annotations and full schema coverage, an agent has everything needed to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters carry detailed in-schema descriptions (limit default, query phrasing guidance). The description adds no parameter information of its own, so the 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+resource ('Search for available Markifact operations') plus a scoping condition ('that can be executed by the authenticated user'). This clearly distinguishes it from siblings like get_operation_inputs and run_operation.
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 an explicit workflow chain (find_operations → get_operation_inputs → run_operation/run_write_operation), states the selection rule for read vs write ('when requires_approval: true'), and forbids calling run tools without first inspecting the schema. It also tells the agent how to recover when a query misses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a signed URL for a private file.
Use this when an operation returns a file_id and you need a temporary,
directly accessible URL. Operation file_url values are user-facing app URLs
that require Markifact authentication; call this tool to generate a signed URL that
the model or external tools can open directly. The signed URL expires after 1 hour.
Returns a signed GCS URL for the file.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The file identifier or filename (e.g. "file-abc123.json", "chart.png") Pass the full filename including its extension. If an extensionless prefix matches multiple files, the tool returns an ambiguity error. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description contributes genuinely new behavior: the signed URL expires after 1 hour and the result is a GCS URL openable by the model or external tools, whereas the operation's `file_url` needs Markifact authentication. It does not discuss failure modes or retry behavior, but the ambiguity error is already documented in the 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?
Front-loaded with the core purpose and well organized into purpose, when-to-use, contrast, and return. The closing sentence 'Returns a signed GCS URL for the file' restates the opening line rather than adding information, a small 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?
With an output schema present, return values need no elaboration, and annotations carry the safety profile. What remains — purpose, when to use it versus the authenticated `file_url`, and the 1-hour expiry — is fully covered for a single-parameter 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% and the schema already explains that a full filename with extension is expected and that extensionless prefixes can trigger an ambiguity error. The description adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Get a signed URL for a private file' — and immediately distinguishes its output from the 'file_url' values that appear on operations. An agent can tell it apart from siblings like read_file or upload_media without opening a 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 says when to reach for it ('when an operation returns a `file_id` and you need a temporary, directly accessible URL') and contrasts it with the authenticated user-facing `file_url` values. The alternative is named and the condition that selects this tool over it is stated, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the input schema, required fields, defaults and constraints for an operation.
Required step between find_operations and run_operation/run_write_operation. Call this once per operation_id before executing it — schemas contain nested objects, account selectors, and field names that vary per operation and cannot be guessed. If you already retrieved the schema for this operation_id earlier in the conversation, reuse it instead of calling again. Only pass fields from this schema in run_operation/run_write_operation input_data for the same operation_id.
Returns JSON schema describing the operation's inputs.
| Name | Required | Description | Default |
|---|---|---|---|
| operation_id | Yes | Exact Markifact operation ID returned by find_operations, e.g. 'gads_get_report'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds non-obvious context beyond that: the per-operation_id granularity, the reuse-instead-of-recall behavior, and the guarantee that field names vary per operation and cannot be guessed.
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 purpose, then the workflow constraint and the reuse rule, then the return note. Slightly longer than strictly necessary, but each sentence carries distinct operational guidance rather than 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 an output schema present, the description need not detail return values, and it still names what comes back ('JSON schema describing the operation's inputs'). For a one-parameter, read-only lookup whose role is positional in a workflow, nothing an agent needs is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single operation_id parameter already documents its format and source ('Exact Markifact operation ID returned by find_operations'). The description reinforces the same idea but adds no format or syntax detail the schema lacks, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('get the input schema ... for an operation') and enumerates what is returned (required fields, defaults, constraints). It clearly separates itself from find_operations and run_operation by framing itself as the schema-lookup step between them.
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 sequencing ('required step between find_operations and run_operation/run_write_operation'), a per-operation_id call cadence, a caching exclusion ('reuse it instead of calling again'), and a downstream rule limiting input_data to schema fields. No ambiguity about when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved Markifact connections for an app/platform.
A connection is a saved authenticated integration in Markifact. The
returned id is the connection_id used to choose which saved
login/integration an operation should use.
Important:
connection_id is not an external platform account ID.
External account IDs, customer IDs, property IDs, and similar values are separate operation inputs.
One connection may have access to multiple external accounts.
In most cases, you don not need to provide connection_id.
If the user has only one connected login for a platform in their workspace,
operations usually use that connection automatically. Use this tool only
when the user wants a specific saved integration or has multiple
connections for the same platform.
Returns JSON with available connections containing id, type, and
display_name.
| Name | Required | Description | Default |
|---|---|---|---|
| connection_type | No | Optional app/platform filter. Examples: 'gads', 'ga4', 'meta_ads', 'hubspot', 'slack'. Leave empty to list all available connections. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description adds real semantics: connection_id is not an external platform account ID, external account/customer/property IDs are separate operation inputs, and one connection can span multiple external accounts. That is behavioral context an agent cannot get from 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?
Front-loaded with the core purpose, then cleanly bulleted into the important disambiguation and the when-to-use rule. It runs slightly long and contains a typo ('you don not need'), but nearly every sentence carries distinct meaning.
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 an output schema present, the description needn't explain return shape, and it still names the relevant fields it returns ('id', 'type', 'display_name'). Combined with full annotation coverage and a fully described parameter, nothing an agent needs to call this 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 the single parameter already documents itself with examples ('gads', 'ga4', 'meta_ads') and the leave-empty behavior, so the schema does the heavy lifting. The description reinforces the app/platform filtering concept but adds no syntax or format detail beyond the schema, making the baseline 3 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 ('List saved Markifact connections') and goes further by defining what a connection is ('a saved authenticated integration') and what the returned id is for. An agent can distinguish this from operation-running siblings like run_operation or find_operations 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?
Explicitly states the negative case first ('In most cases, you do not need to provide connection_id... operations usually use that connection automatically') and then the positive trigger ('Use this tool only when the user wants a specific saved integration or has multiple connections for the same platform'). This is textbook when-to-use / when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a signed upload URL for a media file selected in the upload UI.
Returns upload details including file_id, file_url, upload_url and upload_token, or a validation error.
| Name | Required | Description | Default |
|---|---|---|---|
| file_name | Yes | Name of the selected media file. | |
| file_size | No | File size in bytes. Defaults to 0 if omitted. | |
| content_type | Yes | Image or video MIME type of the selected file. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 that the URL is 'signed' and returns an 'upload_token', implying credential minting, plus the possibility of a validation error — useful context, but no expiry, permission, or side-effect details beyond that.
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, purpose front-loaded before the return details. Enumerating file_id, file_url, upload_url and upload_token is mildly redundant given the output schema, but it is compact and wastes little 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 an output schema covering return values and annotations covering the safety profile, the description only needs to establish purpose and workflow position. It establishes purpose but omits where this step sits relative to upload_media, leaving the agent to infer the upload sequence on its own.
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 file_name, file_size and content_type are already fully documented in the schema, including the default of 0 for file_size. The description adds no format, constraint, or size-limit information on top of 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?
Names a specific verb and resource: creating a signed upload URL for a media file. The scope ('selected in the upload UI') is concrete and helps separate it from the sibling upload_media, though the relationship to that sibling is never stated explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the phrase 'a media file selected in the upload UI', which hints this is a preparatory step in a UI flow. There is no explicit when-to-use statement, no exclusions, and no reference to the upload_media sibling that presumably performs the actual transfer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a file returned by a previous operation as numbered lines of text.
Use this when an operation returns a file_id and you want to inspect the
file contents before deciding what to do next. This is mainly useful for
exported JSON, CSV, logs, and similar files produced by Markifact
operations.
It returns the file as numbered text lines so you can quickly review the structure, schema, headers, sample rows, or specific sections in chunks.
Returns formatted text with line numbers.
After inspecting, you can use {{file-id}} in other tool inputs to pass the full parsed content for processing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of lines to read (default: 100, max: 5000) | |
| offset | No | Starting line number (0-indexed, default: 0) | |
| file_id | Yes | File identifier from previous operations (e.g., "file-WWIIe") |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: chunked line-numbered output, and the follow-up workflow of passing `{{file-id}}` into other tool inputs to get full parsed content.
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 first sentence front-loads the core purpose and the length is reasonable for the workflow described. It is slightly padded: "Returns formatted text with line numbers" restates the opening sentence and the third sentence adds little.
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?
An output schema exists, so return values need not be explained, and the description still usefully covers the trigger, the chunked-inspection use case, and the downstream `{{file-id}}` flow. The main omission is any distinction from the sibling `get_file_url`.
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 `limit`, `offset`, and `file_id` are already fully documented in the schema. The description only alludes to chunked reading and sample-row inspection, adding no syntax or default details beyond what the schema supplies. 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?
The description gives a specific verb and resource: inspect a file previously returned by an operation, rendered as numbered lines. It clearly scopes the input to files carrying a `file_id`. It does not differentiate from the sibling `get_file_url`, which an agent could easily confuse with this 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?
It states a clear trigger -- use when an operation returns a `file_id` and you want to inspect contents before deciding next steps -- and names the file types it suits (exported JSON, CSV, logs). No explicit when-not condition or named alternative is given, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit actionable product feedback to Markifact with the user's authorization.
When you encounter a likely Markifact bug, missing capability, or product limitation while completing a task, proactively tell the user what you found and offer to report it to Markifact. You may draft a concise proposed report for the user to review.
Call this tool only after either:
the user explicitly asks you to submit the feedback, or
you offered to report a discovered issue and the user explicitly agreed.
If the user's request already clearly authorizes submission, do not ask for redundant confirmation. Do not call this tool merely to ask for permission, and do not submit feedback silently.
This tool creates an irreversible feedback submission in Markifact's support workflow. The submission contains the supplied feedback, relevant operation IDs, and account-associated contact and reference identifiers. After a successful call, briefly tell the user that the feedback was submitted.
Report only issues Markifact itself caused. Low-level operations such as gads_mutate or meta_ads_update_adset pass requests straight to the platform, so their responses are the platform's, not Markifact's. A write the platform accepted is complete; if the state differs later, something else changed it. If you are unsure how a platform behaves, research its documentation. Never report third-party policies, outages, rate limits, rejected content, campaign performance, or user configuration.
For a potentially missing integration capability, use the normal operation discovery flow to check whether Markifact already provides a dedicated or generic operation that supports the requested action. Do not execute a write operation merely to test whether a capability exists.
Include only the minimum non-sensitive concrete evidence needed to understand the issue. Never include passwords, API keys, access tokens, authentication details, payment information, raw conversation history, complete request or response payloads, or unrelated personal or customer data. Summarize relevant errors and behavior instead of copying raw data.
Avoid duplicate or repetitive reports. Use other only when the feedback
does not fit another category. Write the title and description in English.
Do not promise that Markifact will respond or implement a fix.
Returns JSON confirming whether the feedback was successfully submitted to Markifact support.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Concise English title describing the Markifact issue, up to 140 characters. | |
| impact | Yes | Severity based on blocked work and affected scope: low, medium, or high. | |
| category | Yes | Feedback type: bug, feature_request, improvement, or other. | |
| description | Yes | Concise English explanation of the expected behavior, actual behavior, user impact, and minimal non-sensitive evidence, up to 10,000 characters. | |
| operation_ids | No | Relevant Markifact operation IDs, when known. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and idempotentHint=false, and the description adds the crucial context the annotations cannot: the submission is 'irreversible,' what it contains (feedback, operation IDs, account contact/reference identifiers), the required user consent flow, and post-call guidance. It also discloses the important boundary that low-level passthrough operations (gads_mutate, meta_ads_update_adset) return platform responses, not Markifact's, so they shouldn't be reported here.
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?
Long but front-loaded and organized: purpose, when-to-call, consent conditions, behavioral/disclosure notes, scope exclusions, content hygiene, and return value all in distinct paragraphs. It is longer than strictly necessary and could shed a little redundancy, but every paragraph earns its place given the consent and safety stakes.
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 destructive, open-world, non-idempotent submission tool with an output schema present, the description is essentially complete: it covers authorization, irreversibility, payload contents, scope boundaries, sensitive-data rules, and a brief return-value note. Since an output schema exists, it needn't detail return structure further.
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 value beyond the schema: it requires title and description in English, instructs including only minimum non-sensitive evidence, forbids secrets, and warns to avoid duplicate reports and use 'other' only when no other category fits. It doesn't walk through all five params, but it meaningfully enriches the key content and category 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?
Explicit verb+resource: 'Submit actionable product feedback to Markifact.' It clearly distinguishes itself from siblings, which are all operation-discovery and execution tools (find_operations, run_operation, etc.), none of which submit feedback. An agent can select this without 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?
Unusually strong. It states the trigger condition ('When you encounter a likely Markifact bug, missing capability, or product limitation'), the two precise authorization gates for calling, explicit anti-patterns ('Do not call this tool merely to ask for permission,' 'do not submit feedback silently'), and exclusions ('Never report third-party policies, outages, rate limits...'). It even routes capability questions to the normal operation discovery flow rather than testing by executing a write.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a read-only Markifact operation, such as fetching reports, listing records, selecting accounts, or looking up account details.
Use this in direct response to the user's current request. Do not use it for startup checks or background context gathering.
For write/create/update/delete actions, use run_write_operation instead.
Operations returned by find_operations with requires_approval: true MUST be executed via run_write_operation.
operation_id must be an exact Markifact operation ID returned by find_operations for the authenticated user.
Never call this without first inspecting the schema via get_operation_inputs. Input shapes, nested objects, and field names vary per operation and cannot be guessed.
input_data must contain only fields from the get_operation_inputs schema for the same operation_id.
Reporting tips
Reporting operations (GA4, Google Ads, Meta Ads, etc.) require account IDs. Use the relevant select_accounts operation first, treating user-provided account names as substring matches.
Never guess metric or dimension values. Use the relevant list_report_fields operation to confirm available fields before building a report.
For Google Ads, always prefer using the gads_get_report operation. Use gads_run_gaql_query only for advanced or unsupported reporting queries.
Files
Some operations may return file_id when datasets are too large. You will also receive a small data_preview for context.
You can reference any file ID in other operation inputs using this syntax: {{file-id}}, for example: {"data": "{{file-xe3fw}}"} (exactly as provided—do not modify or invent file ids).
When you pass a file_id to another operation, the file content will be automatically loaded and converted to the correct data type. JSON becomes Python dict/list, CSV/XLSX becomes a list of dicts (rows), and images/binary files become raw bytes. You do not need to handle parsing or conversion—just pass {{file-id}}.
The file ID is for you to move data between operations efficiently. When sharing results with the user, always share links using the get_file_url tool.
Returns JSON with the operation result.
| Name | Required | Description | Default |
|---|---|---|---|
| input_data | Yes | Dict matching the selected operation's schema from get_operation_inputs. Pass {} if no inputs are needed. | |
| operation_id | Yes | Exact Markifact read operation ID returned by find_operations, e.g. "meta_ads_select_accounts", "gads_list_report_fields", "ga4_get_report". |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds substantial context beyond that: it requires operation_id to be exact and from find_operations for the authenticated user, mandates schema inspection via get_operation_inputs, warns that input shapes cannot be guessed, explains the file_id exchange mechanism and automatic type conversion, and describes the return format. It does not contradict 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 long but front-loads purpose and usage, then organizes remaining details under clear headings (Reporting tips, Files). Each section earns its place by addressing a distinct operational concern for a complex generic dispatch tool. No filler or redundant restatement.
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 an output schema exists, the description needn't explain return values, yet it still notes that JSON is returned. It covers prerequisites, alternatives, file handling, reporting-specific guidance, and authentication context. For a nested-object, two-parameter dispatch tool with rich annotations, the description is fully adequate.
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 baseline is 3. The description adds meaningful constraints: operation_id must be an exact Markifact operation ID returned by find_operations for the authenticated user (with examples), and input_data must contain only fields from the get_operation_inputs schema for the same operation_id. This goes beyond the schema and helps prevent malformed calls.
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 (Execute) and resource (read-only Markifact operation), gives concrete examples of operation types, and explicitly contrasts with run_write_operation. An agent can immediately tell what this tool does and how it differs from its write sibling.
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 explicit when-to-use (direct response to current request) and when-not-to-use (startup checks, background context gathering), names the alternative run_write_operation for write actions, and states a hard prerequisite that operations with requires_approval:true must go through run_write_operation. It also mandates inspecting the schema via get_operation_inputs before calling. Nothing 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.
Execute a write operation that creates, updates, or deletes external data.
Use this tool ONLY for operations marked with requires_approval: true in
find_operations results. These are destructive actions like creating campaigns,
updating ad statuses, sending emails, etc.
operation_id must be an exact Markifact operation ID returned by find_operations for the authenticated user.
APPROVAL REQUIRED: Every call writes irreversibly to the user's live external accounts. Before each invocation, summarize the exact change in plain language (operation, target account/resource, key field values) and wait for explicit user confirmation. Never call without user's confirmation, approval is CRITICAL.
Never call this without first inspecting the schema via get_operation_inputs. Input shapes, nested objects, and field names vary per operation and cannot be guessed.
input_data must contain only fields from the get_operation_inputs schema for the same operation_id.
Write-operation tips
Always prefer a dedicated operation when one already matches the task.
Some platforms have a generic fallback operation for create, update, or remove mutations not covered by a dedicated operation, for example gads_mutate for Google Ads. Use the fallback before reporting a missing write feature.
Files
Some operations may return file_id when datasets are too large. You will also receive a small data_preview for context.
You can reference any file ID in other operation inputs using this syntax: {{file-id}}, for example: {"data": "{{file-xe3fw}}"} (exactly as provided—do not modify or invent file ids).
When you pass a file_id to another operation, the file content will be automatically loaded and converted to the correct data type. JSON becomes Python dict/list, CSV/XLSX becomes a list of dicts (rows), and images/binary files become raw bytes. You do not need to handle parsing or conversion—just pass {{file-id}}.
The file ID is for you to move data between operations efficiently. When sharing results with the user, always share links using the get_file_url tool.
Returns JSON with the operation result.
| Name | Required | Description | Default |
|---|---|---|---|
| input_data | Yes | Dict matching the selected operation's schema from get_operation_inputs. Pass {} if no inputs are needed. | |
| operation_id | Yes | Exact Markifact write operation ID returned by find_operations, e.g. "gads_create_campaign", "gads_edit_responsive_search_ad", "meta_ads_update_campaign_budget", "sheets_write_data". |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive/openWorld/not-readOnly, but the description goes well beyond them: an approval workflow with per-call confirmation, the warning that every call writes irreversibly to live external accounts, the dependency on get_operation_inputs for unknown input shapes, and file_id substitution semantics.
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 rule and organized under headed sections, but there is some duplication ('Never call without user's confirmation, approval is CRITICAL' restates the bolded APPROVAL REQUIRED block) and the Files section is lengthy for a tool whose return values are already covered by an output 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 two-param, dynamically-typed dispatcher tool, the description covers the full invocation contract: preconditions (find_operations, get_operation_inputs), approval gate, data-passing conventions, and fallback strategy. Return values are covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by constraining operation_id to an exact ID returned by find_operations for the authenticated user, requiring input_data to only contain fields from get_operation_inputs for the same operation_id, and explaining the {{file-id}} reference syntax.
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: 'Execute a write operation that creates, updates, or deletes external data.' It also implicitly distinguishes itself from the read-side sibling run_operation and names sibling tools (find_operations, get_operation_inputs) that gate its use.
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 routing: use ONLY for operations flagged requires_approval: true from find_operations, and never call before inspecting get_operation_inputs. It also names the preferred alternative (dedicated operations first) and the fallback pattern (gads_mutate) before reporting a missing feature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload an image or video asset for later operations.
Use this when the user needs to provide media that will be reused in later tool calls, for example creating Facebook ad image or video asset, or a Google Ads creative flow. The tool returns file URLs that can be passed into later operations that accept uploaded media. Only image and video uploads are supported.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 mutation and safety profile is covered structurally. The description adds the supported-media constraint ('Only image and video uploads are supported') and that it returns URLs, but says nothing about auth prerequisites, file size limits, or what happens on repeated uploads.
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 action, then usage guidance, then the return contract in four short sentences. Efficient, with only mild redundancy between the opening line and the return-value 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?
An output schema exists, so return values need not be re-explained, and annotations cover safety. But for a tool with an empty input schema and a closely named sibling in the same flow, the description omits the one thing an agent most needs: how media is provided and when to reach for upload_media rather than prepare_media_upload.
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 zero parameters, which sets the baseline at 4. However, the input schema is an empty object with additionalProperties=false, and the description never explains how the media is actually supplied to the call - that mechanism is left entirely implicit.
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 ('Upload an image or video asset') and adds the intended downstream purpose ('for later operations'). It does not distinguish itself from the sibling prepare_media_upload, which appears to be part of the same upload flow, so an agent cannot tell the two apart from the text 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 a clear trigger condition ('when the user needs to provide media that will be reused in later tool calls') plus two concrete example flows (Facebook ad image/video asset, Google Ads creative flow). No exclusions or guidance on how it relates to prepare_media_upload or run_operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
