FalaAI API (MCP)

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

No annotations are supplied, so the description carries the full burden and does so thoroughly: it discloses credit charging, the stateless nature (nothing persisted, LGPD protection), the text-only confidence downgrade, and the conditional html_report. It also warns the agent to relay the full response because the result is not stored and re-calling re-charges.

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 and outputs, then inputs, then billing caveats, which is a sensible order. However it is a single dense block and the closing IMPORTANT paragraph largely restates the earlier credit-charging and non-persistence points, adding length beyond what the ideas require.

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

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

For a 9-parameter tool with no output schema and no annotations, the description supplies the missing return format, conditional outputs, billing behavior and data-handling posture. An agent has everything needed to invoke it correctly and relay results.

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 0% schema coverage and 9 parameters, the description compensates fully: it specifies the dialog turn format, the text fallback, the 300k character cap, the duration_seconds >= last turn end rule, the language requirement, the fixed model value, response_language defaulting, participants (up to 10, roles, ground-truth vs inferred) and the client_reference_id charset/length.

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 (analyzes) and resource (call transcript) and enumerates the six return blocks, so an agent knows exactly what it produces. It also explicitly differentiates itself from the sibling risk_audit by scoping this tool to generic diagnosis versus compliance auditing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use ('fast, generic diagnosis of what happened in a call') and a named alternative with its selecting condition ('use /v1/analyze/riskAudit instead when the goal is compliance violation auditing'). It also distinguishes dialog vs text input paths, leaving nothing to inference.

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

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

No annotations exist, so the description carries the full burden and does so: credits are charged, the exact charged amount is in usage.credits_consumed, preview costs nothing (credits_charged=0), the endpoint is stateless with in-memory processing and temp files removed, and the result is NOT stored. It even warns that calling again charges again and instructs the agent to relay the full response.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose, preview mode, window rules, parameters, limits and output are all front-loaded in a logical order with almost no filler. The downside is a dense run-on delivery with no visual breaks, which makes the conditional logic harder to scan than it needs to be for a definition this 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?

No output schema exists, yet the description describes both return objects in detail: whatsapp_preview with credits_total, params used, windows, per-conversation items and warnings; and conversations with id (wc-), usage, per-conversation fields (conversation_id, first_at, last_at, duration_seconds, speakers, dialog, message_count, characters) plus meta. Nothing needed to invoke or interpret the 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?

With 0% schema description coverage across 13 parameters, the description compensates almost completely: file_base64/filename encoding, timezone and date_format required with the three allowed values, windows as a JSON string of start/end sub-objects with union/dedup semantics, gap_minutes (720), min_messages (2), voice_note (true), expression (true), and client_reference_id charset/length. Start/end edge cases (empty, all-zeros, omitted-in-dry_run) are also covered.

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: extracts and segments conversations from a WhatsApp export (.zip or .txt), with AI transcription of voice/audio/video and description of visual expressions in the non-preview path. The two modes (dry_run preview vs. charged extraction) are clearly delineated. It doesn't distinguish itself from the sibling transcribe_audio, which is the one plausible point of confusion for a media-transcribing 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?

Explicit routing: dry_run=true for validation/estimate without AI or charge; outside preview it consumes credits. Names the alternative path for oversized exports (>45 MB must go to POST /v1/whatsapp/extractConversations as multipart, limit 1 GB). Also spells out window-selection rules and which parameter combinations are rejected.

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

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

With no annotations provided, the description carries the full burden and discharges it well: it is free, consumes no credits, requires no API key (public endpoint), performs no analysis, and stores nothing. These are exactly the cost/side-effect facts an agent needs before deciding to call it.

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 what it does, then when to use it, then cost/side-effect guarantees. Every clause earns its place; nothing is redundant with structured fields.

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 no-parameter tool with no output schema, the description supplies the missing return shape (status, version, uptime, database, phase, launch date) and the missing safety/cost profile. 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline credit applies. No misleading parameter claims are made.

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 ("Checks the connection to the FalaAI API and returns its health and version") and even enumerates the returned fields. It is clearly distinguishable from siblings like diagnostic or risk_audit because it is framed as the pre-flight connectivity check.

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 ordering guidance ("Use it FIRST to confirm the MCP is working before any billable call"), which tells the agent exactly when to invoke it. It does not name a specific alternative sibling to use later, so it stops short of full when/when-not routing.

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

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

With no annotations, the description carries the full burden and delivers: it discloses that the call consumes credits, that the exact charge is returned in response.meta.usage.credits_consumed, that the operation is stateless with only billing/usage metadata logged, and explicitly warns that nothing is persisted so the caller must relay and save the full response. This is exactly the kind of cost/side-effect/retention context an agent needs before invoking.

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?

Content is dense and front-loaded with purpose before parameter detail, and almost every clause delivers a constraint. It loses a point for redundancy: the credit-charging and non-persistence facts are stated twice (mid-paragraph and again in the closing IMPORTANT sentence), and the single unbroken paragraph makes scanning harder than it needs to be.

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

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

Despite no output schema, the description fully enumerates the V2 return shape (meta+usage, participants, verdict, scores, detections, frameworks, timeline, categories_summary, executive summary, scoring explanation, gzip+base64 HTML report) and adds the operational caveat that the response is not stored. Nothing essential for correct invocation or result handling 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 0%, so the description must compensate and does so extensively: dialog format string with speaker-label variants and 300k char cap, duration_seconds consistency constraint (>= last turn end), the pt-BR/en-US/es-ES enum for language and response_language, audio_events limit of 500, participants limit of 10 with role values, call_direction values, response_format 'v2', and client_reference_id charset and max length.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ('Runs a compliance risk audit on a diarized call transcript') and enumerates the specific processing steps (violation/positive detection, ISO 31000 matrix, risk-level classification, NIST/OWASP framework mapping). It explicitly separates itself from the sibling space by ruling out generic summarization, so an agent can distinguish it from transcribe_audio or diagnostic 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?

Gives a clear when-to-use ('compliance and quality audits of company-agent-to-client calls') and a when-not ('not for generic conversation summarization'). It stops short of naming the sibling tools (e.g., transcribe_audio for raw transcription) that an agent should route to instead, so the alternative mapping is left implicit rather than explicit.

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

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

With zero annotations the description carries the full burden and does so: it discloses credit consumption, statelessness/no persistence under LGPD, the 64 MB body cap and ~45 MB practical file limit, the 3-hour duration cap, accepted MIME types, and that client_reference_id is not an idempotency key. It also warns that repeat calls re-charge and mandates relaying the full response before the result is lost.

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 and output shape, then limits, then per-parameter notes, so scanning is easy. It is long and mildly redundant — 'This call consumes credits' is restated in the IMPORTANT block — and the exhaustive MIME/language lists bulk it up, though both are operationally necessary.

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 paid, stateless, size-constrained transcription tool with no output schema and no annotations, the description covers input encoding, limits, cost, retention, return fields and post-call handling obligations. An agent has everything needed to call it correctly and safely without inspecting the schema.

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

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

Schema description coverage is 0%, yet the description documents all five parameters: file_base64 as base64 of raw bytes, optional filename, model default 'falaai-transcribe-1' as the only valid value (schema default is null, so this adds real information), language as a two-letter code with the full accepted set and auto-detect behavior, and client_reference_id with charset, 60-char cap and echo 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+resource ('Transcribes one uploaded audio file into text with speaker diarization and timestamped audio events') and immediately enumerates the returned artifacts. Nothing about the sibling tools (diagnostic, health, risk_audit, extract_whatsapp) could be confused with this, and the single-file scope is 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?

Gives a concrete trigger ('Use it when a recording must become text for analysis, review or storage of the transcript') and routes oversized inputs to an explicit alternative (POST /v1/audio/transcriptions multipart, 1 GB limit). No 'when not to use' or sibling-level exclusion is stated, but none of the siblings are plausible substitutes.

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