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 are supplied, so the description carries the full burden and does so thoroughly: it discloses credit consumption, that dry_run charges nothing, the 1GB file limit, the stateless in-memory processing with temporary files removed, and the imperative to relay the full chargeable result.

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 purpose and key constraints are front-loaded, and nearly every sentence carries load-bearing detail, so the length is justified by the tool's complexity. However, it is delivered as one very dense run-on block that is hard to parse, which costs it a point.

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 covers the return shape: the preview object (credits_total, params, windows, items, warnings) and the paid result (conversations with conversation_id, timestamps, speakers, dialog, counts) plus usage and meta. Nothing an agent needs is missing.

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

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

Schema coverage is 0%, yet the description documents essentially all 13 parameters: file_base64, filename, dry_run, start/end vs windows semantics, timezone, date_format enum values, gap_minutes (720), min_messages (2), voice_note (true), expression (true), and the client_reference_id charset/length constraint.

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, then resolves them with AI via transcription and visual-expression description. An agent can clearly tell what it does, though it does not explicitly differentiate from the sibling transcribe_audio.

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

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

Provides rich when-to-use guidance: dry_run=true for a free validating preview, and the rules for choosing windows vs start/end. It does not name alternative tools, so it stops short of the explicit 'use X instead' routing that would warrant a 5.

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

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

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 no annotations, the description carries the full burden and does so: credit consumption with credited/re-import warning, 1GB/3-hour limits, stateless in-memory processing (LGPD, never persisted), the fact that the result is NOT stored, and the instruction to relay the entire response. This is exactly the behavioral context an agent needs before spending credits on an irreversible call.

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 usage before the parameter and behavioral detail, and the IMPORTANT warning is correctly placed last. The MIME-type and language enumerations are long, but they are the only documentation of those constraints anywhere, so they earn their space rather than being 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?

For a cost-incurring, stateless tool with no output schema, the description enumerates every returned field (id, language, language_confidence, duration_seconds, text, dialog, audio_events, event_types, word_count, input metadata), so the agent knows what to expect and relay. Nothing needed to call it correctly or handle its result 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 0%, so the description must compensate and does: file_base64 is defined as base64 of the file bytes with filename optional, model is documented as defaulting to the only supported value, language is documented with the full accepted code list and auto-detect behavior, and client_reference_id is given a charset, a 60-char cap and the explicit note that it is echoed verbatim and is not an idempotency key.

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 ('Transcribes one uploaded audio file into text') plus the differentiating capabilities (speaker diarization, timestamped audio events) and the exact return shape. An agent can immediately tell this apart from siblings like risk_audit or extract_whatsapp.

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 ('when a recording must become text for analysis, review or storage of the transcript') and the scoping constraint that it handles a single file. It does not name any alternative tool or state when NOT to use it, but the sibling set offers no competing transcription option, so the omission is minor.

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