Preconfigured AI tools for the back office. Speaker separation, mermaid diagrams, meeting summarize, invoice processing, youtube analyzer, AI session inspection
Scored across 27 tools
Most tools target clearly distinct job types or management actions, so an agent can select the correct task in the common case. Minor overlap exists between get_file_download_url and get_job_result_asset_url, and between the two upload-URL helpers, but the descriptions provide clear disambiguation rules.
Names are consistently snake_case and mostly follow a verb_noun pattern for operations (create_, get_, list_, update_, delete_, cancel_). The main deviation is that several job-start tools are noun phrases (audio_redaction, bg_remover, invoice_processor), which is readable but not fully uniform.
The server covers several distinct subdomains—AI processing jobs, file handling, credits, and MCP server management—so many tools are justified. However, 27 tools is heavy for a single MCP surface, and the set could likely be decomposed or consolidated for easier agent use.
Core workflows are well covered: job creation/listing/status/cancellation, file listing/downloading, credit reporting, uploads for key media types, and full MCP server CRUD plus connection testing. Minor gaps remain, such as generic file deletion or broader upload helpers, but agents can work around them.
Start an audio PII-redaction job for a recording already stored in this organization. Returns a job handle immediately; fetch the redacted transcript, the list of entity types stripped, and the redacted-audio file id later with get_job. Pass audioFileUrl as a storage path from list_files (mimeCategory "audio") — this tool cannot upload media itself, so a caller with a local file must upload it in the web app first. Download the bleeped copy with get_file_download_url using redactedAudio.fileId. Redaction is automatic and should be reviewed by a human before the output leaves the organization.
| Name | Required | Description | Default |
|---|---|---|---|
| policies | No | PII categories to strip. Omit for the default set (names, contact details, and financial identifiers). An unlisted category is rejected rather than ignored, so a typo cannot produce a job that reports success while leaving that category in the audio. | |
| audioFileUrl | Yes | Storage path of an audio file already uploaded to this organization (e.g. organizations/<orgId>/files/<name>.mp3). Call list_files with mimeCategory "audio" to find it — do not guess a path. This tool cannot upload media itself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare non-readonly, non-idempotent, non-destructive, but the description adds genuinely new behavior: the call returns a job handle immediately (asynchronous), it cannot ingest media itself, and an unlisted policy category is rejected rather than silently ignored. Missing details on job duration, concurrency limits, or failure modes keep it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, each front-loaded with a distinct operational fact (start, fetch, input source, download, review). Some phrasing repeats the schema text for audioFileUrl, which is the only real slack.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return contract itself: a job handle now, and transcript/entity list/redactedAudio.fileId later via get_job. Combined with the input and review guidance, an agent has everything needed to call it and follow up.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds non-schema context: a local-file caller must upload via the web app before calling, and omitting policies yields the default set. Much of the audioFileUrl wording duplicates the schema description, so this is not maximal.
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?
Opens with a specific verb+resource+scope: 'Start an audio PII-redaction job for a recording already stored in this organization.' An agent can distinguish this from siblings like bg_remover or speaker_separation and cannot confuse it with a generic job 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?
Explicitly routes the agent: find the file via list_files with mimeCategory "audio", fetch results later with get_job, download the bleeped copy with get_file_download_url. It also states a hard precondition (no media upload; upload in the web app first) and a human-review requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a background-removal job. Returns a job handle immediately; fetch the transparent-PNG cutout later with get_job. Pass EITHER imageUrl (a public https:// URL, which the server downloads) OR imageFileUrl (a storage path from list_files with mimeCategory "image") — exactly one, never both. This tool cannot accept raw file bytes, so a caller holding only a local file must upload it in the web app first or host it at a public https:// URL. Download the cutout with get_file_download_url (cutout.fileId) or get_job_result_asset_url (role "cutout").
| Name | Required | Description | Default |
|---|---|---|---|
| imageUrl | No | Publicly reachable https:// URL of the image to cut out. The server downloads it. Only https:// is accepted, and URLs resolving to private, loopback, link-local, or cloud-metadata addresses are rejected. Pass this OR imageFileUrl, never both. | |
| imageFileUrl | No | Storage path of an image already uploaded to this organization (e.g. organizations/<orgId>/files/<name>.png). Call list_files with mimeCategory "image" to find it — do not guess a path. Pass this OR imageUrl, never both. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare openWorldHint=true and non-idempotent, but the description adds contract-level detail the annotations cannot convey: the job is asynchronous, the server performs the download, a job handle is returned rather than the artifact, and raw bytes are unsupported. These are the exact behavioral traits an agent needs to plan a multi-call workflow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads what the tool does and its return contract before the parameter constraints and retrieval path. Every sentence carries new information — no filler, no restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by explaining what comes back (a job handle) and exactly how to turn it into the final cutout PNG, including both retrieval tools and the argument to pass. An agent can complete the whole async flow without guessing.
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 are fully documented there, including the https-only and private-address restrictions and the mutual-exclusivity rule. The description largely restates the either/or constraint, adding only minimal framing, 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?
Opens with a specific verb+resource ('Start a background-removal job') and immediately clarifies the async contract ('Returns a job handle immediately'). This clearly distinguishes it from synchronous siblings like audio_redaction and from the retrieval tools (get_job, get_file_download_url) it references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing: use either imageUrl or imageFileUrl (exactly one), and names the follow-up tools and their arguments for retrieving the result. It also states a negative condition — 'cannot accept raw file bytes' — and names the two recovery paths (upload via web app, or host publicly).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a job the caller can access by its id (recovers a mistaken or duplicate submission). An API token can cancel any job in its organization, so an id from list_jobs may belong to a human teammate — cancel only a job the user explicitly identified. Only jobs still in PENDING state can be cancelled; a job already PROCESSING or COMPLETED returns an error — poll get_job first if unsure. Refunds the credit only if the job had not started processing.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the mutation/idempotency profile; the description goes further by disclosing state preconditions (only PENDING is cancellable), the error behavior for PROCESSING/COMPLETED, and the credit-refund rule tied to whether processing began. These are behavioral traits the annotations cannot convey.
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 purpose, then safety caveat, then state constraint, then refund rule — four clauses, each load-bearing, no filler. Sized appropriately for a mutation tool with real failure modes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and sparse annotation coverage, the description compensates fully: preconditions, error outcomes, and the monetary side effect are all present. An agent has everything needed to call this correctly or avoid calling it wrongly.
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 0% and the single jobId param is untyped in prose, but the description adds real semantic context: the id must be one the user explicitly identified, and an org-wide token means ids from list_jobs may not be the caller's. That is meaningfully more than the schema's 'string, minLength 1'.
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 ('Cancel a job ... by its id') with the caller-scope qualification, and implicitly routes against siblings by contrasting with get_job/list_jobs. An agent can identify exactly what this does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('recovers a mistaken or duplicate submission'), plus a when-not/alternative path ('poll get_job first if unsure') and a safety exclusion (don't cancel a teammate's job merely found via list_jobs). This is close to ideal routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mint a short-lived signed URL for uploading speaker-separation audio. Three steps: (1) call this tool with filename, mimeType, and optional size; (2) HTTP PUT the raw file bytes to signedUploadUrl with Content-Type set to the same mimeType before expiresInSeconds elapses; (3) call speaker_separation with the returned path as audioFileUrl. Do not POST the bytes to this tool. Returns signedUploadUrl, path, bucket, expiresInSeconds, maxBytes, and allowedMimeTypes.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | File size in bytes. Rejected if it exceeds the returned maxBytes. | |
| filename | Yes | Original filename including extension (e.g. meeting.mp3). | |
| mimeType | Yes | MIME type of the audio file. Must match the Content-Type header on the subsequent HTTP PUT. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false); the description adds real behavioral detail beyond that: URL expiry (expiresInSeconds), size rejection via maxBytes, allowed mime types, and the required Content-Type match on the follow-up PUT. It even enumerates the returned fields despite no output 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, then three numbered steps each occupying one sentence, closed by a terse return-field list. No filler sentences; every clause carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the full lifecycle: inputs, the out-of-band PUT, expiry/mime/size constraints, and the exact fields returned, all without an output schema. An agent has everything needed to complete the upload and hand off to speaker_separation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description earns extra credit by tying mimeType to the downstream Content-Type header requirement and framing size as optional and validated against maxBytes, clarifying how each parameter participates in the workflow rather than just restating types.
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 ('mint a short-lived signed URL for uploading speaker-separation audio') and implicitly scopes it against siblings by routing the upload through speaker_separation. An agent can distinguish it from create_invoice_upload_url and get_file_download_url immediately.
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 three-step procedure with sequencing: call this tool, then HTTP PUT the bytes, then call speaker_separation with the returned path. It also states a negative constraint ('Do not POST the bytes to this tool'), which is exactly the when-not guidance agents need.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mint a short-lived signed URL for uploading an invoice PDF or image. Three steps: (1) call this tool with filename, mimeType, and optional size; (2) HTTP PUT the raw file bytes to signedUploadUrl with Content-Type set to the same mimeType before expiresInSeconds elapses; (3) call invoice_processor with the returned path, bucket, and mimeType. Do not POST the bytes to this tool. Returns signedUploadUrl, path, bucket, expiresInSeconds, maxBytes, and allowedMimeTypes.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | File size in bytes. Rejected if it exceeds the returned maxBytes. | |
| filename | Yes | Original filename including extension (e.g. invoice.pdf). | |
| mimeType | Yes | MIME type of the invoice (PDF or image). Must match the Content-Type header on the subsequent HTTP PUT. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the mutation profile (readOnly=false, destructive=false, idempotent=false). The description adds substantive behavior beyond that: the URL is short-lived, it expires after expiresInSeconds, uploads exceeding maxBytes are rejected, and the PUT must carry a matching Content-Type. This is exactly the context annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose, then enumerates the steps and outputs in tight sentences. No filler; every clause carries operational 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?
There is no output schema, but the description enumerates the return fields (signedUploadUrl, path, bucket, expiresInSeconds, maxBytes, allowedMimeTypes), and covers the full initiation-to-handoff flow. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description ties each parameter to the workflow step and reinforces the cross-field constraint that mimeType must equal the subsequent PUT's Content-Type, which aids correct invocation beyond the field-level schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource ('mint a short-lived signed URL for uploading an invoice PDF or image') and implicitly distinguishes itself from the sibling create_audio_upload_url by naming the invoice artifact and the downstream invoice_processor.
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 three-step workflow, names the required inputs, states the negative constraint ('Do not POST the bytes to this tool'), and routes to the successor tool invoice_processor with the exact fields to pass. Nothing about when/how to use it 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.
Register a new external MCP upstream server for the org. The URL is SSRF-validated; any authValue is encrypted at rest.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Streamable-HTTP endpoint of the upstream MCP server. | |
| name | Yes | Unique per-org identifier for the server (1–50 chars). | |
| enabled | No | ||
| authType | No | none | |
| authValue | No | Plaintext upstream credential (bearer token or header value). Encrypted at rest; never returned. | |
| transport | No | http | |
| headerName | No | Header name for authType="header" (e.g. "X-Api-Key"). | |
| description | No | ||
| displayName | No | ||
| selectedTools | No | Allow-list of upstream tool names. null = all allowed, [] = none, [names] = only those. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), but the description adds genuinely new behavioral facts: the URL is SSRF-validated and authValue is encrypted at rest. It stops short of stating failure modes (e.g. duplicate name collisions) or whether a connection test is triggered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the core action front-loaded and the security caveat second. Nothing to trim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter creation tool with conditional auth fields and no output schema, the description leaves the auth-parameter combinations, the allow-list behavior, and the identity of the created resource unexplained. It is minimally viable given annotations cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% across 10 parameters (enabled, authType, transport, description, displayName are undocumented in the schema), so the description carries a heavier burden — yet it adds nothing about parameters beyond echoing that authValue is encrypted, which the schema already states. No guidance on how authType, headerName and authValue interact, or on selectedTools semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Register a new external MCP upstream server for the org.' The create/update/delete family is inferable from the name and sibling list, but the description itself never contrasts this with update_mcp_server or test_mcp_server_connection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, and no routing to alternatives such as update_mcp_server (for existing servers) or test_mcp_server_connection (to verify one). The agent must infer everything from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an org-scoped MCP upstream server and its stored credential.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description contributes one genuine extra fact — that the stored credential is removed as well — but says nothing about irreversibility, permissions, or behavior on a missing id.
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?
One sentence, zero filler, and the destructive scope and side effect are front-loaded before the credential detail. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema and annotations that fully cover the destructive/idempotency profile, the description covers the essentials. The only shortfall is the absence of an irreversible-action warning and any hint about the 'id' argument.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description never mentions the single required 'id' parameter, so it adds no semantics (e.g., what identifier namespace it belongs to) beyond the bare field name. With one documented-but-unexplained parameter, the description fails to compensate for the coverage gap.
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 ('Delete an org-scoped MCP upstream server') and adds the scope and a side effect ('its stored credential'), which is more than a tautology. The verb naturally separates it from create_mcp_server, update_mcp_server, get_mcp_server, and list_mcp_servers, though no sibling is named 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?
There is no statement of when to use this versus alternatives (e.g., update_mcp_server for credential rotation) and no prerequisites or warnings about irreversibility. The only guidance is what is implied by the word 'Delete'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current credit balance and status for the caller's active organization.
| 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 openWorldHint=false, so safety is covered. The description adds useful scope ('caller's active organization') and notes that the return includes both balance and status, but it does not disclose auth requirements, rate limits, or what 'status' entails 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 a single front-loaded sentence with no wasted words. It states the resource, the scope, and the returned fields efficiently.
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, zero-parameter read operation with no output schema, the description is largely complete: it identifies the resource, the organizational scope, and the returned fields. It could be improved by briefly differentiating from get_credit_history and get_credit_usage_stats, but no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to clarify. Per the rubric, a zero-parameter tool earns a baseline of 4, and the description does not need to compensate for any schema gaps.
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 ('Get') and resource ('credit balance and status') for a clearly scoped subject ('caller's active organization'). However, it does not distinguish this tool from close siblings like get_credit_history or get_credit_usage_stats, which an agent might confuse it with.
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 offers no explicit when-to-use guidance or mention of alternatives. The word 'current' implies this is for the latest balance rather than historical data, but the agent is not told when to choose this over get_credit_history or get_credit_usage_stats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List paginated credit transactions for the caller's active organization (grants, usage, refunds, purchases). Filter by tool slug, type, or date window. Does not spend credits.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter to a single transaction type. | |
| limit | No | Max transactions to return (1–100; defaults to 50). | |
| offset | No | Transactions to skip for pagination (defaults to 0). | |
| endDate | No | Inclusive ISO-8601 end of the window. | |
| toolSlug | No | Filter to a single tool slug, e.g. "speaker-separation". | |
| startDate | No | Inclusive ISO-8601 start of the window. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces the non-mutating profile with 'Does not spend credits' while adding pagination behavior and org scoping not present in the annotations. It stops short of disclosing ordering or default-window behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the resource and scope, then filters, then the safety note. No filler and no repetition.
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 read-only, zero-required-param listing tool with no output schema, this covers resource, scope, filters, and safety. It would be marginally stronger if it hinted at what a transaction record contains or the default ordering, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (type, limit, offset, dates, toolSlug all documented), so the schema carries the parameter burden. The description only restates the filter axes already in the schema, adding no new syntax or format detail; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List paginated credit transactions') plus the scope ('caller's active organization') and enumerates the record kinds (grants, usage, refunds, purchases). It is clear, but it never names the nearest siblings (get_credit_balance, get_credit_usage_stats), so the agent must infer the boundary from the transaction-type list 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?
'Filter by tool slug, type, or date window' implies the read/ledger-lookup use case, and 'Does not spend credits' hints at a safe inspection context. However, there is no explicit when-to-use-this-vs-alternatives guidance against get_credit_balance or get_credit_usage_stats, so routing depends on inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregated credit usage for the caller's active organization: totals, spend by tool, and spend by day. Optional startDate/endDate window. Does not spend credits.
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | No | Inclusive ISO-8601 end of the window. | |
| startDate | No | Inclusive ISO-8601 start of the window. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. Beyond them, the description adds the notable reassurance 'Does not spend credits' — valuable because credit tooling often has side effects — and clarifies scope is limited to the caller's active organization. It does not cover pagination or result limits, which are minor given the read-only annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: the purpose and returned breakdown come first, the optional window second, and the no-side-effect reassurance last. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by describing the return shape (totals, spend by tool, spend by day) and the org scoping. Annotations carry the safety profile, so an agent has enough to call it correctly, though the sibling routing and parameter window semantics remain underexplained.
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 are optional, so the schema already documents startDate/endDate inclusive ISO-8601 semantics. The description only restates that they form an optional window, adding no format or default-behavior detail beyond the schema — the baseline 3 for fully covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get aggregated credit usage') and enumerates the aggregation dimensions returned (totals, by tool, by day). It implicitly separates itself from get_credit_balance and get_credit_history by calling out aggregation, but it never names those siblings to make the distinction explicit.
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: the agent can infer this is the reporting/summary tool while balance and history cover other needs, but the description never says when to pick this over get_credit_balance or get_credit_history. 'Does not spend credits' hints at a when-not condition without stating one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mint a short-lived (1 hour) signed download URL for a file in the caller's organization. Pass fileId from list_files or from a completed job's output (audio_redaction.redactedAudio.fileId, bg_remover.cutout.fileId). The URL is a capability for that object — do not share it outside the organization. A file from another organization is refused.
| Name | Required | Description | Default |
|---|---|---|---|
| fileId | Yes | File id from list_files, or from a completed job's output (e.g. audio_redaction.redactedAudio.fileId, bg_remover.cutout.fileId). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description adds real value: a 1-hour TTL, capability semantics ('do not share it outside the organization'), and cross-organization refusal. It omits permission/auth details and rate-limit behavior, so not quite 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?
Three tight sentences, front-loaded with the core action and TTL, then sourcing, then security constraint. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, low-complexity tool with no output schema, the description covers what is produced, its lifetime, how to obtain the input, and the key constraint. Nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage on a single parameter, the schema already documents fileId and its sources; the description largely restates the same provenance. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource ('Mint a short-lived signed download URL for a file') plus the org scope. An agent can distinguish it from sibling URL tools such as get_job_result_asset_url and create_audio_upload_url 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?
Tells the caller where to source fileId (list_files or a completed job's output, with concrete paths like audio_redaction.redactedAudio.fileId) and when a call is refused. It stops short of explicitly contrasting with the similar sibling get_job_result_asset_url, so routing between the two still requires inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the status and output of a job by its id. An API token can fetch any job in its organization, including ones a human teammate started in the web app. Speaker-separation output includes the labeled transcript and segments (txt-ready); rename speakers afterward with update_speaker_labels. For a downloadable file, use get_file_download_url with a fileId from the output, or get_job_result_asset_url for a background-remover cutout/source.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnlyHint/openWorldHint, and the description adds real behavioral context beyond that: an API token can read any job in its organization, including human-started web-app jobs. It also describes what speaker-separation output contains. It stops short of return-shape or error behavior, but the scope disclosure is genuinely additive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action before the sibling routing. Every clause carries actionable content; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does explain that the return is status plus output and details the speaker-separation payload, plus where to get file downloads. It could say more about generic output/status values, but it is adequate for a single-param read 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 0% for the single jobId param, and the description only says 'by its id', which largely restates the schema's property name and type. No format, origin, or validity detail is added to help the agent supply or derive the id.
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 ('Fetch the status and output of a job by its id'), which cleanly separates it from list_jobs and cancel_job. It further anchors itself by naming the sibling tools it is not (update_speaker_labels, get_file_download_url, get_job_result_asset_url).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing conditions: rename speakers via update_speaker_labels after reading speaker-separation output, and use get_file_download_url or get_job_result_asset_url when a downloadable file is needed. The agent can pick among four siblings without opening another schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mint a short-lived (1 hour) signed download URL for a background-remover result image (role "cutout" or "source") on a job the caller can access. Prefer get_file_download_url when the job output already has a fileId. Other tools have no cutout/source assets.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | Which background-remover image to sign: the transparent PNG cutout, or the original source. Other tools have no assets for these roles. | |
| jobId | Yes | Id of a job the caller can access. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond them: the URL is short-lived (1 hour), signed, and requires access to the job. No pagination or error behavior is described, but for a simple read that is minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action and expiry, then routing guidance. The closing clause 'Other tools have no cutout/source assets' duplicates text already in the schema's role description, which is slight redundancy but harms nothing.
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 is simple (2 params, no output schema), and the description covers what is produced (a short-lived signed URL), the access requirement, and the alternative to use. Nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both jobId and role are already documented in the schema, including the enum meanings. The description restates the role options and the access constraint but adds no syntax or format detail beyond that, matching the baseline 3.
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 (mint), resource (signed download URL), the object (background-remover result image with role cutout/source) and the scope (a job the caller can access). An agent can distinguish this from get_file_download_url without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative and the selecting condition: 'Prefer get_file_download_url when the job output already has a fileId.' It also notes that other tools have no cutout/source assets, so the routing decision is fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one org-scoped MCP upstream server by id (secrets stripped).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a genuine behavioral fact beyond that: returned secrets are stripped, which tells the agent what it will and won't receive.
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?
One compact sentence, front-loaded with verb and resource, and the parenthetical qualification is placed where it is needed. Nothing is wasted or buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must set expectations for the return value; it names only that secrets are stripped and omits the shape of the server object and not-found behavior. Adequate for a trivial one-param read, but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single id parameter carries no schema description. The description only implies 'id' and adds the org-scoping constraint, without stating format, source, or how to obtain a valid id — insufficient compensation for the coverage gap.
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 an MCP upstream server) and the scope (org-scoped, by id). The phrase 'one ... by id' implicitly distinguishes it from list_mcp_servers, though no sibling is named 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 implied by 'by id' versus the list_mcp_servers sibling, but there is no explicit statement of when to fetch a single server instead of listing, and no mention that the id comes from a prior list call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an invoice-extraction job. Returns a job handle immediately; fetch vendor, totals, and line items later with get_job. Pass invoiceText, OR filePath + bucket + mimeType from create_invoice_upload_url. To upload a local PDF or image: (1) call create_invoice_upload_url, (2) HTTP PUT the raw bytes to signedUploadUrl with the declared Content-Type before the URL expires, (3) call this tool with the returned path, bucket, and mimeType.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | No | Storage bucket returned by create_invoice_upload_url. Required together with filePath. | |
| filePath | No | Storage path returned by create_invoice_upload_url after you HTTP PUT the raw document bytes. | |
| mimeType | No | MIME type of the uploaded invoice (the same value declared when minting the upload URL). | |
| invoiceText | No | Pasted invoice text to extract. Pass this OR a file reference (filePath + bucket + mimeType). | |
| outputFormat | No | Result format. Defaults to json when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), and the description adds meaningful behavior on top: it returns a job handle immediately rather than results, and the signed upload URL must be used before it expires. It does not discuss auth, rate limits, or retry/idempotency implications, but the async contract is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and async return, then the input mode, then the numbered upload procedure. Every clause carries operational information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by explaining that a handle is returned and results are fetched via get_job, and it resolves the zero-required-parameter ambiguity by defining the two valid input combinations. Nothing essential for a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented in the schema, including the invoiceText-vs-file-reference exclusivity. The description reinforces the mutually exclusive input modes but adds nothing about outputFormat or the enum values, so the baseline 3 holds.
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 ('Start an invoice-extraction job') and immediately clarifies the async contract by naming get_job as the retrieval sibling. An agent can distinguish this from create_invoice_upload_url and get_job 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 states the two accepted input modes ('Pass invoiceText, OR filePath + bucket + mimeType from create_invoice_upload_url') and lays out the three-step local-file upload flow, including the ordered dependency on create_invoice_upload_url and the expiry constraint. Alternatives and conditions are fully spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files in the caller's active organization, newest first. Filter by mimeCategory (audio/image/video/document/other), filename search, or tag ids. Each row includes id, filename, mimeType, size, storagePath, bucket, tags, and uploadedBy. Use storagePath as speaker_separation/audio_redaction audioFileUrl or bg_remover imageFileUrl; use id with get_file_download_url. Does not list another organization's files.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page (defaults to 1). | |
| search | No | Case-insensitive filename search (e.g. "standup"). | |
| tagIds | No | Only files that have at least one of these tag ids. Tag ids are returned on each file from this tool. | |
| pageSize | No | Results per page (1–100; defaults to 20). | |
| mimeCategory | No | Filter by file kind. Use "audio" to find recordings for speaker_separation or audio_redaction; "image" for bg_remover. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=true and openWorldHint=false, so safety is handled. The description adds real value beyond them by disclosing ordering (newest first), the org scoping limitation, and the exact row fields returned (id, filename, mimeType, size, storagePath, bucket, tags, uploadedBy), which matters because there is no output 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-loads the core action, then filters, then return fields, then cross-tool routing - a logical progression with no filler. Slightly dense, but every clause (ordering, field list, downstream routing) carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully enumerates the returned columns and their downstream consumers, plus ordering, filtering options, and scope limits. Nothing needed 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%, so every parameter (page, search, tagIds, pageSize, mimeCategory) is already documented, and the enum is spelled out. The description echoes the mimeCategory use-case mapping that the schema already contains, adding little net-new semantics. 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 (list) and resource (files) with scope (caller's active organization) and ordering (newest first). An agent can immediately distinguish this listing tool from siblings like list_jobs or get_file_download_url.
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 clear context for use and routes the agent downstream: storagePath feeds speaker_separation/audio_redaction/bg_remover, and id pairs with get_file_download_url. It also states a negative constraint (does not list another organization's files) but stops short of explicit when-not alternatives among the sibling listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the jobs the caller can access, optionally filtered by tool slug. An API token sees its whole organization's jobs, including ones a human teammate started in the web app; a signed-in user sees their own jobs and those of tokens they created.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max jobs to return (1–100; defaults to 20). | |
| offset | No | Jobs to skip for pagination (defaults to 0). | |
| toolSlug | No | Filter to a single tool slug, e.g. "news-analyzer". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: visibility differs by auth mode, and API tokens see org-wide jobs including human-started ones. It does not address ordering or pagination semantics, but the schema covers defaults.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The primary action is front-loaded, and the visibility nuance follows as supporting context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a filtered list tool with full schema coverage, no required params, and a read-only annotation, the description supplies the key missing piece (visibility scope). Return shape is not explained, but no output schema exists and list semantics are conventional; ordering could be mentioned but is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit, offset, and toolSlug are already documented with defaults and ranges. The description repeats the tool-slug filter concept without adding syntax or constraints beyond the schema. 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?
Specific verb (list) + resource (jobs) + scope (jobs the caller can access), with the optional tool-slug filter named. It is clearly distinguishable from get_job, which retrieves a single job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when the scope applies (API token vs signed-in user) and that filtering by tool slug is optional. It does not explicitly name alternatives such as get_job for a single job or pagination-based iteration, but the context for use is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the org's configured external MCP upstream servers (secrets stripped; hasAuth flag 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 openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: secrets are stripped from the response and only a hasAuth flag is exposed, which tells the agent what data it will and won't receive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with the resource stated first and the response caveat parenthetically appended. Every clause carries information; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must carry return-shape burden, and it does so partially by stating secrets are stripped and only a hasAuth flag is returned. It does not describe other returned fields (e.g. ids, names, connection state), leaving a modest gap for a read tool of this kind.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. No parameter meaning is lost.
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 (List) and a precisely scoped resource (the org's configured external MCP upstream servers). An agent can separate it from get_mcp_server (singular retrieval) and list_files by resource name 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?
The listing scope implies enumeration use, but there is no explicit when-to-use guidance, no mention of when to prefer get_mcp_server for a single server, and no prerequisites stated. Usage is inferable from the name and description rather than declared.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a meeting-minutes job. Returns a job handle immediately; fetch the structured minutes later with get_job. Pass meetingNotes (pasted text) OR sourceJobId (a completed speaker_separation job in this organization — no re-upload). Minutes include a summary, decisions, action items with owners and deadlines when stated, speaker attribution, timestamp references, and open questions. 2 credits per run. Creates a new job; the source speaker-separation job is never changed or deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| meetingDate | No | Optional meeting date (YYYY-MM-DD). | |
| meetingType | No | standup | planning | retrospective | one_on_one | client | general. Defaults to general. | |
| sourceJobId | No | Id of a completed speaker_separation job in this organization. Minutes are built from that job's labeled transcript (speaker names + timestamps). Creates a new job; the source job is not changed. Pass this OR meetingNotes. | |
| meetingNotes | No | Pasted meeting notes or a transcript. Pass this OR sourceJobId, not both required. | |
| participants | No | Optional attendee names. Inferred from speaker labels when sourceJobId is used. | |
| projectContext | No | Optional project or team context for the minutes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint false, destructiveHint false, idempotentHint false), and the description adds context those flags cannot: it returns a job handle immediately rather than minutes, costs 2 credits per run, and crucially guarantees the source speaker-separation job is 'never changed or deleted'. The async/credit/reversibility details are exactly the behavioral traits an agent needs beyond structured hints.
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 action and async return are front-loaded, followed by input routing, output contents, and cost/guarantees in a tight sequence. It is dense but each sentence carries distinct information; only the enumeration of minute contents is mildly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly takes on the burden of describing what the minutes contain (summary, decisions, action items with owners/deadlines, speaker attribution, timestamps, open questions). Combined with the async job pattern, cost, and non-destructive guarantee, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the description adds value by characterizing meetingNotes as pasted text, clarifying sourceJobId points at a completed speaker_separation job whose labeled transcript is reused without re-upload, and previewing the minute contents. It doesn't add format/syntax detail beyond the schema, so it sits just above 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?
The opening sentence gives a specific verb and resource ('Start a meeting-minutes job') and immediately frames it as an async job that returns a handle, which distinguishes it from synchronous siblings like get_job. It also names the sibling tool (speaker_separation) it can consume input from, so an agent can separate it from adjacent tools 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?
It states the two mutually exclusive input routes (meetingNotes OR sourceJobId) and directs the agent to get_job for retrieval, and explains the condition that makes sourceJobId valid ('a completed speaker_separation job in this organization — no re-upload'). It does not spell out when-not-to-use this tool versus any alternative summarization path, so it stops short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a news-article analysis job (bias, entities, sentiment). Provide either articleUrl or articleText. Returns a job handle immediately; fetch the result later with get_job.
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | ||
| articleUrl | No | URL of the news article to analyze. | |
| articleText | No | Raw article text to analyze (use instead of articleUrl). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds the key non-obvious behavior: this is an asynchronous job that returns a handle immediately and requires a later get_job call. That async contract is the critical trait and is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero filler, front-loaded with the action and the input constraint before the retrieval step. Every sentence carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a job-starting tool with no output schema, the description correctly tells the agent that the return is a job handle and how to retrieve results. It omits what happens if both articleUrl and articleText are supplied and any mention of cost/limits, but the essential contract is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% and the schema already documents articleUrl and articleText individually; the description adds the either/or relationship between them, which the schema does not state. The nested 'options' object (includeRelated, includeSources) is left unexplained, keeping this from a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Start') and resource ('news-article analysis job') and enumerates the analysis dimensions (bias, entities, sentiment). This is clearly distinguishable from siblings like get_job or youtube_transcript.
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?
Explains the input choice ('Provide either articleUrl or articleText') and the follow-up workflow ('fetch the result later with get_job'), naming the sibling tool. It stops short of explicit when-not guidance or prerequisites, but the async usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a quote-check job. Returns a job handle immediately; fetch per-item verified / paraphrase_supported / unsupported / misattributed findings later with get_job. Pass sourceJobId (a completed meeting_summarizer job in this organization that chained from speaker_separation) OR summary plus transcriptJobId (a completed speaker_separation job). Checks quotes, decisions, and action items against the labeled transcript. 2 credits per run. Creates a new job; the minutes and transcript jobs are never changed or deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| summary | No | Pasted minutes or a summary to check. Required with transcriptJobId when sourceJobId is omitted. | |
| sourceJobId | No | Id of a completed meeting_summarizer job in this organization that itself chained from speaker_separation (that minutes job has sourceJobId). Quote Check reads the minutes and the labeled transcript. Creates a new job; neither source is changed. Pass this OR summary + transcriptJobId. | |
| transcriptJobId | No | Id of a completed speaker_separation job in this organization. Required with summary when sourceJobId is omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond annotations: returns a job handle immediately (async), costs 2 credits per run, and guarantees the minutes and transcript jobs are never changed or deleted. This clarifies the destructiveHint=false / idempotentHint=false annotations in concrete terms.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the async return pattern, then the input contract, then the assurance about sources and cost. Every sentence carries distinct, necessary information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema present, the description correctly compensates by stating the immediate return (a job handle) and how to obtain results (get_job), plus cost and side-effect guarantees. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema descriptions already explain the required-with relationship for each parameter, so the description largely restates it. The added detail about chaining provenance is helpful but not beyond what the structured fields convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Start a quote-check job') and describes exactly what gets checked (quotes, decisions, action items against the labeled transcript). It clearly distinguishes itself from siblings like meeting_summarizer and speaker_separation by naming them as upstream dependencies.
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 either/or invocation contract (sourceJobId OR summary + transcriptJobId), specifies the required upstream job states ('completed meeting_summarizer job that chained from speaker_separation'), and routes the agent to get_job for retrieving findings later.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a review VOC-pack job. Cluster competitor reviews into pain themes with cited quotes. Pass reviewUrls and/or corpus (paste G2/Capterra/Trustpilot reviews — those sites are not fetched). Optional maxReviews and focus (pricing | support | bugs | other). Returns a job handle immediately; fetch themes, featureGaps, and positioningHooks later with get_job. Themes are synthesized; verify quotes before publishing.
| Name | Required | Description | Default |
|---|---|---|---|
| focus | No | Optional theme filter: pricing, support, bugs, or other. | |
| corpus | No | Pasted review text (preferred). One review per paragraph or a JSON array of {text,url,rating}. | |
| maxReviews | No | Maximum reviews to cluster (default 50, cap 200). | |
| reviewUrls | No | Review page URLs the user already has. We fetch a page only when robots/ToS allow it. G2, Capterra, Trustpilot, and similar aggregators are never fetched — paste those reviews in corpus. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as a non-read-only, open-world, non-idempotent job. The description adds genuinely useful behavior beyond that: it returns a handle immediately (async pattern), and warns that themes are synthesized and quotes must be verified before publishing. No destructive/auth details, but the async and reliability caveats are valuable.
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?
Four sentences, each load-bearing — purpose, inputs, options, return/next step. Front-loaded with the action and no filler; the verification caveat is well placed at the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the returned job handle and downstream fields (themes, featureGaps, positioningHooks) available via get_job. Adequate for an async job tool, though job lifecycle/failure behavior is not covered.
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, but the description adds real meaning: it clarifies corpus should hold pasted G2/Capterra/Trustpilot reviews because those sites aren't fetched, and frames focus as an optional theme filter. This resolves the corpus-vs-reviewUrls decision beyond the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Start a review VOC-pack job' — then names the exact output (pain themes with cited quotes). This is clearly distinguishable from siblings like get_job or news_analyzer.
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?
Explains the operating context: pass reviewUrls and/or corpus, aggregator sites are never fetched so their reviews must be pasted, and results are retrieved later via get_job. Lacks an explicit when-not-to-use statement against alternatives, but the workflow routing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a speaker-separation job for audio already stored in this organization. Returns a job handle immediately; fetch the labeled transcript (txt-ready) later with get_job. Pass audioFileUrl as a storage path from list_files (mimeCategory "audio") or from create_audio_upload_url — this tool does not accept raw or base64 audio. To upload a local file: (1) call create_audio_upload_url, (2) HTTP PUT the raw bytes to signedUploadUrl with the declared Content-Type before the URL expires, (3) call this tool with the returned path as audioFileUrl. After completion, rename speakers with update_speaker_labels.
| Name | Required | Description | Default |
|---|---|---|---|
| audioFileUrl | Yes | Storage path of audio already in this organization (e.g. organizations/<orgId>/files/<name>.mp3). Use list_files (mimeCategory "audio") for a file that is already uploaded, or the path returned by create_audio_upload_url after you HTTP PUT the raw bytes. This tool does not accept raw or base64 audio. | |
| languageCode | No | ISO language code that overrides automatic language detection (e.g. "en", "ar"). Omit for auto-detect. | |
| audioMetadata | No | Optional filename, mimeType, duration, and size of the uploaded file. | |
| speakersExpected | No | How many distinct speakers to look for (1–10). Omit to let diarization detect the count. | |
| estimatedDurationSeconds | No | Duration estimate in seconds used for create-time credit metering. Omit to charge a 1-minute floor, then reconcile against the processed length. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the mutation profile (readOnlyHint=false, idempotentHint=false), and the description adds genuinely new behavior: the call is asynchronous and returns a job handle immediately rather than results. It also spells out the three-step upload prerequisite, which annotations do not cover. It stops short of any rate-limit or failure-mode detail, so not a full 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and return behavior, then the workflow. Dense but each sentence carries operational weight. Minor redundancy between the description's audioFileUrl explanation and the identical schema text keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly fills that gap by naming the return value (job handle) and the retrieval path (get_job). Combined with the upload prerequisite and post-processing step, an agent has everything needed to invoke this tool correctly in sequence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter including the storage-path format, language override, speaker count, and metering behavior. The description largely restates the audioFileUrl constraint rather than adding syntax or format detail beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Start a speaker-separation job') and immediately scopes it to 'audio already stored in this organization'. An agent can distinguish it from siblings like audio_redaction or meeting_summarizer 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 names the alternatives (list_files with mimeCategory "audio", create_audio_upload_url) and states the exclusion ('does not accept raw or base64 audio'). It also gives the follow-up lifecycle path: get_job for results and update_speaker_labels for renaming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List an org-scoped upstream server's tools and optionally cache the discovered tool names on success (persist=true). Returns { ok, tools } or { ok:false, error } without leaking secrets.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| persist | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds value beyond those annotations by disclosing the persist caching behavior, the return shape ({ok, tools} or {ok:false, error}), and the security note that secrets are not leaked. It does not contradict any annotation.
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 tightly written sentences: the first gives the action and optional caching behavior, the second gives the return shape and security constraint. Front-loaded and free of 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 only two parameters, no output schema, and annotation coverage for safety hints, the description supplies the missing return-value information and caching behavior. It is largely complete for the tool's complexity, though it could mention authentication or error conditions more explicitly for a connection-testing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning. It explains the persist parameter's effect (cache discovered tool names on success) and implies that id identifies an org-scoped upstream server, but it does not explicitly define the id parameter or its expected format. Partial compensation for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it lists an upstream server's tools and can cache the discovered names. It is distinguishable from most sibling MCP server tools (create/get/delete/update), though it does not explicitly name an alternative. The title 'Test MCP server connection' adds slight framing but the description clarifies the concrete behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what happens with persist=true but does not say when to use this tool versus alternatives such as get_mcp_server, list_mcp_servers, or update_mcp_server. No when-to-use, when-not-to-use, or prerequisite guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an org-scoped MCP upstream server. Supplying authValue rotates the stored credential; omitting it leaves the existing one.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| url | No | Streamable-HTTP endpoint of the upstream MCP server. | |
| name | No | Unique per-org identifier for the server (1–50 chars). | |
| enabled | No | ||
| authType | No | ||
| authValue | No | Plaintext upstream credential (bearer token or header value). Encrypted at rest; never returned. | |
| transport | No | ||
| headerName | No | Header name for authType="header" (e.g. "X-Api-Key"). | |
| description | No | ||
| displayName | No | ||
| selectedTools | No | Allow-list of upstream tool names. null = all allowed, [] = none, [names] = only those. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: partial-update semantics for authValue (supplying it rotates the credential, omitting it preserves the existing one), which the agent cannot infer from annotations or schema alone.
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 compact sentences, front-loaded with the operation and scope, with the credential-rotation nuance immediately following. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter, no-output-schema mutation tool, the description covers the key credential behavior but leaves the other partial-update fields (enabled, authType, transport, etc.) and their interplay unexplained. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 45%, so several parameters (enabled, authType, transport, description, displayName) lack documentation in both schema and description. The description does add valuable omission semantics for authValue, but it does not compensate for the undocumented majority.
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 ('Update an org-scoped MCP upstream server'), which cleanly separates it from create_mcp_server, get_mcp_server, and delete_mcp_server by virtue of the verb. It does not explicitly name those siblings, but the scope qualifier 'org-scoped' adds precision beyond the bare name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to update versus recreate, nor any prerequisites or notes about related tools like test_mcp_server_connection. Usage is only implied by the verb 'Update'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename speakers on a completed speaker-separation job. Pass jobId and speakers [{ id, label }] using the speaker ids from get_job (e.g. "A", "B"). Empty labels revert to Speaker X. Segment speaker ids are unchanged. Only a completed speaker-separation job in the caller's organization can be renamed.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Id of a completed speaker-separation job the caller can access. | |
| speakers | Yes | One entry per speaker to rename. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds useful behavior beyond them: empty labels revert to 'Speaker X', segment speaker ids are unchanged, and only completed jobs in the caller's org can be renamed. This scope/permission context is valuable, though it doesn't describe the return or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences, front-loaded with the core action and then the mechanics. Every sentence carries a distinct fact (ids source, empty-label behavior, segment id stability, access scope) with no waste.
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 mutation tool with no output schema, the description covers behavior, scope, and prerequisites adequately. The only minor gap is that it doesn't state the return value or failure modes, but annotations and the full schema coverage carry the rest.
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 documents jobId, id, and label fully. The description restates the id source (get_job, e.g. "A", "B") and the empty-label behavior, which largely duplicates the schema descriptions rather than adding new meaning. 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 (rename) and resource (speakers on a completed speaker-separation job), clearly distinguishing it from siblings like get_job or speaker_separation. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: it applies only to a completed speaker-separation job in the caller's organization, and the speaker ids should come from get_job. It does not name a competing alternative tool explicitly, but the constraints make when-to-use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a YouTube transcript-analysis job. Returns a job handle immediately; fetch the result later with get_job.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| lang | No | ||
| mode | No | native |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so safety/network profile is partly covered. The description adds the valuable async disclosure that a job handle is returned immediately and results are retrieved separately via get_job, which is a real behavioral trait beyond the annotations, but it omits credit cost, failure behavior, and result shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and then the handoff to get_job. No filler, every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and three undocumented parameters, the description should carry more of the burden. It says nothing about what the transcript job actually returns, what mode controls, or whether lang defaults matter, leaving significant gaps for a tool an agent must invoke 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 0%: url, lang, and mode are all undocumented in the schema. The description adds nothing about any parameter – notably the meaning of mode's native/generate/auto enum and the lang selection are left completely unexplained, so an agent must guess.
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 ('Start a YouTube transcript-analysis job'), which is concrete and actionable. It does not explicitly differentiate itself from job-oriented siblings like meeting_summarizer or news_analyzer, but the async-job framing is clear enough that an agent knows what it produces.
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 one piece of workflow guidance – fetch the result later with get_job – which is genuinely useful for the async pattern. It offers no when-to-use vs alternatives guidance and says nothing about the relationship to cancel_job or list_jobs, so usage context is only implied.
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.
audio_redactionbg_removercancel_jobcreate_audio_upload_urlcreate_invoice_upload_urlcreate_mcp_serverdelete_mcp_serverget_credit_balanceget_credit_historyget_credit_usage_statsget_file_download_urlget_jobget_job_result_asset_urlget_mcp_serverinvoice_processorlist_fileslist_jobslist_mcp_serversmeeting_summarizernews_analyzerquote_checkreview_voc_packspeaker_separationtest_mcp_server_connectionupdate_mcp_serverupdate_speaker_labelsyoutube_transcript
Add one secure layer between your agents and this server.