Sapiens Sintéticos

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

Annotations only declare readOnlyHint=false and openWorldHint=true, and the description adds substantial context beyond that: the method stays server-side and the agent refuses to reveal it (a refused call still consumes a round), the exact cost and daily cap, refund-on-model-failure, synchronous execution taking up to ~90 seconds, and the credit-check procedure on Timeout. It also instructs presenting the delivery verbatim with code blocks.

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 and sub-actions are front-loaded, and nearly every clause carries operational information (limits, cost, timeout handling, display instruction). It is nevertheless a single dense run-on paragraph where the per-agent detail for 'maquinista' is stacked into the middle, making it slightly harder to scan than a short structured list would 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?

There is no output schema, and the description compensates fully: it says run returns the deliverable as text with each pasteable piece in a code block, and instructs echoing it as-is. Combined with cost, rate limit, timeout, and refund behavior, an agent has everything needed to call this correctly and interpret the result.

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 still adds meaning: it constrains 'conceito' to 4,000 characters, explains it is the concept rather than the whole briefing, lists what it may contain (theme/mood/sound or pasted lyrics), and documents the in-concept slash commands (/styleline, /hooks, /tighten, /spice, /unloop, /audit) that no schema field mentions. It also confirms 'agente' is the short name as returned by list.

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 — runs an authorial Sapiens agent on the person's concept and returns only the finished piece — and enumerates its two sub-actions (list, run) with what each returns. It also names the concrete agent available today ('maquinista') and what it produces, so an agent can distinguish this from neighboring tools 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 for each sub-action ('list' = free, no login; 'run' = needs login, costs 300 Sinapses, 20/day) plus a hard exclusion: don't ask for the manual, rules, or prompt. It also routes to sapiens_meta action=credits before retrying after a Timeout. What it lacks is differentiation from potentially overlapping siblings such as sapiens_musicator or sapiens_write, which also deal with lyrics.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds important behavioral context: identity always comes from sessionToken, access is locked to paid 'Lente' holders, unauthorized users get a purchase notice and no data, and no write operations are possible. This materially helps an agent predict access failures and avoid expecting write behavior. Return format and rate limits are not described, so it is not 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?

The description front-loads the critical read-only and paywall constraints before detailing sub-actions, which is the right structure for agent selection. It is dense but mostly earns its length because it covers four sub-actions and access restrictions. There is slight redundancy around 'READ-ONLY' and 'Nenhuma escrita', preventing 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?

For a multi-action tool with no output schema, the description gives enough context to choose an action and understand access constraints. It explains each sub-action at a high level and clarifies that no data is returned without the paid 'Lente'. It does not describe exact response shapes, but the annotations and schema cover the safety and filtering basics.

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 schema describes ticker, authorHandle, and limit, but the action enum itself has no per-value schema descriptions. The description compensates by explaining what 'overview', 'signals', 'voices', and 'briefings' each return and by noting that ticker and authorHandle apply to signals. This adds useful meaning beyond the schema, though some parameter details remain schema-only.

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

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

The description clearly identifies the resource as the Atlas of the AI ecosystem and explains that it is a read-only, paywalled lookup tool over curated AI value-chain data. It lists the four sub-actions and what each covers, so an agent can understand the tool's scope. It does not explicitly contrast itself with sibling tools such as sapiens_search, keeping it below a 5.

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 tool is for staying informed and answering questions over curated AI value-chain data, and it clearly explains the paid 'Lente' access requirement. However, it does not name when to use this instead of sibling tools or specify what to do when the user lacks access beyond receiving a notice. Usage is implied rather than fully guided.

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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true): discloses per-action costs (150 + ~1350 Sinapses, refund on failure, ~75 for refine, free reroll/persona/favorite/import/font/logo), ownership constraints (only official or your own), that adopt drops persona, and persona requires an existing character image. That is rich behavioral context, though the dense prose sometimes buries 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?

Information-dense but structured as a single sprawling paragraph where sub-actions are enumerated inline; the critical routing rules and cost warnings are not front-loaded. Every fact is relevant, but the wall-of-text form makes scanning for one action costly.

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 15-action, 22-parameter tool with no output schema, the description covers costs, prerequisites, ownership rules, cross-tool dependencies (character, gallery, image), and the import-vs-generate distinction. An agent has essentially everything needed to select and 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 coverage is 95%, so the schema already documents parameters thoroughly; the description adds operational meaning by tying parameters to specific actions and their costs/constraints (e.g., fromSlug requires a briefing-stored brand, import vs generate semantics). It largely complements rather than duplicates the schema, though some reiteration is redundant.

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 precisely what the tool manages (palette, typography, voice, image style, persona as single source of style) and enumerates all 15 sub-actions with their specific effects. It is trivially distinguishable from siblings, explicitly cross-referencing sapiens_character and sapiens_gallery for the relevant flows.

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 routing rules: 'Brand que a pessoa JÁ TEM vai por import, nunca por generate', converse and build a rich description BEFORE calling generate, confirm the 1350 Sinapses cost before generating, and use sapiens_image brandSlug=/brandMark=persona to actually surface the character. When-to-use vs alternatives is spelled out rather than implied.

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?

Annotations only provide readOnlyHint=false and openWorldHint=true; the description adds substantial behavior: Sinapses costs, synchronous/heavy timeout rule, refund-on-failure, 15-slide limit, baseUpdatedAt concurrency rejection, full-payload overwrite risk, and brand/signature defaults. Nothing contradicts the annotations.

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

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

The purpose and skill prerequisite are front-loaded, but the description is one dense paragraph that repeats many sub-action details already present in the schema. The complexity justifies some length, yet scanability and redundancy keep it at 3.

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 still supplies key returns for generate (id + editor url), list (id, title, slide count, url), and get (full payload + layout catalog), plus the editor URL for downloading. It covers edge cases, costs, limits, and handoffs, though not every action's return value is explicit.

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

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

Schema description coverage is 100%, and the schema already documents the action enum, source fields, payload shape, baseUpdatedAt, brandSlug, and most other parameters in detail. The description mostly repeats those parameter semantics; its extra value is workflow-level rather than parameter-level, 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?

The opening sentence names the resource (Instagram carousel), the owner/scope (only that person's carousels), and the descriptor then enumerates all eight sub-actions. It also distinguishes adjacent concerns by pointing to sapiens_skill, sapiens_brand, sapiens_image, sapiens_write, and sapiens_pipeline.

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 explicitly says to pull the 'carrossel' skill before use, gives source-selection rules for generate (brief vs articleId vs userArticleId), explains update handling for externally created carousels, and routes image work to set_image or generate_image. It also flags the timeout rule and cost confirmation for heavy actions.

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?

Annotations only mark the tool as write-capable and open-world, but the description discloses crucial behavior: Sinapses costs for generation actions, synchronous timeout handling, pending:true meaning accepted and billed, email privacy, hidden effects, and permanent deletion. This is substantially beyond the annotations.

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

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

The description is extremely long, with large prose blocks that repeat cost and privacy warnings and restate schema details. It front-loads the resource and action list, but is not concise or easily scannable for a 36-parameter tool.

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

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

Given 21 sub-actions, 36 parameters, no output schema, and minimal annotations, the description is remarkably complete: it covers creation flow, costs, failure modes, return fields such as passport/passportPrompt, hidden, plates, and cross-tool handoffs. An agent has enough information to invoke the tool 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 97%, so the input schema already documents nearly every parameter in detail. The description reinforces relationships like form versus style and name versus fullName, but mostly repeats action-level semantics rather than adding new parameter syntax or constraints, fitting the baseline for high schema coverage.

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 names the resource precisely as 'Personagens (character sheets) do Sapiens' and enumerates the full set of sub-actions. It also distinguishes the tool from siblings such as sapiens_image and sapiens_gallery by explaining that it manages reusable character records tied to the token owner's account.

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 gives explicit when-to-use guidance: the creation flow create → add_image → set_card → activate, when to publish via set_visibility versus activating, when to use list_public versus get/list_mine, and when not to call generate_video without approved shots. It also explains set_hidden versus set_visibility and when to stop and ask the owner before publishing.

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?

Discloses behavior well beyond the annotations: create is born as a private draft with title required; remove detaches the piece without touching the piece itself; note without a note erases it; add on an already-present piece swaps the note; reorder places uncited refIds after the cited ones in their old order; scope is limited to the caller's own account and pieces; and it is free. That is exactly the side-effect detail an agent needs before mutating user data.

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 dense paragraph carrying eight sub-actions, an itemType taxonomy, a naming convention and scope rules — front-loaded correctly with the purpose, but never broken into structure, making it hard to scan for the action the agent actually needs. Nearly every sentence earns its place, but the lack of formatting costs it.

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 eight-parameter, eight-action mutation tool with no output schema, the description covers each action's semantics, required fields, side effects and account scoping, and hints at the shape of get (pieces in order with notes) and list. Return shapes for the other actions are left implicit, which is the only material gap.

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 88%, so the schema already carries most parameter meaning. The description restates rather than extends it: the itemType list, the id-or-slug lookup for `collection`, and the 'escolhida'/'tentativa' note convention all appear in the field descriptions too. The one thing it adds is which sibling tool yields which id per itemType, but that is thin value over an already well-documented schema.

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

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

States a concrete verb+resource: Collections are the album of any piece (image, video, design system, character, etc.) within the user's account, and enumerates the eight sub-actions explicitly. The relation to siblings is only indirect — it names sapiens_image, sapiens_video and sapiens_gallery as sources of ids and rules out publishing/cover-setting (sapiens_publicar territory) — but it never contrasts itself head-on with another collection-ish 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?

Gives real usage context: it is the place for the CHOSEN piece among a project's attempts, with the 'escolhida'/'tentativa' note convention and the reorder-to-top recipe. It also draws an explicit boundary — publishing the Collection and picking a cover are the owner's gestures in the Acervo, never the agent's. It stops short of saying when to use which sibling for listing pieces versus Collections.

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?

Goes well beyond the annotations: server appends '· via Claude', mentions trigger bell + Telegram notifications, emoji allowlist is enforced, media assets are ownership-checked server-side, react is a toggle, and asTese creates a Forum-pingable card. These are exactly the side-effect and constraint details an agent needs before acting.

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 identity and sub-actions, then progressively details mentions, attachments, and voice. Dense but nearly every clause carries actionable information; the all-caps section markers (MENÇÃO, ANEXO) are slightly noisy but aid scanning.

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, 11 parameters, and mixed read/write actions, yet the description covers sub-action selection, side effects, notifications, attachment mechanics, and expected voice. Nothing an agent needs to call any of the actions 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 already 91%, so the schema carries most weight, but the description adds real semantics the schema lacks: how mediaAssetKind+mediaAssetId compose into a card, what asTese does, mention syntax, and where to discover mediaAssetId. This nudges above 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 resource (community chat for subscribers + alumni) and enumerates the five sub-actions with a one-line gloss for each. An agent can tell exactly what this tool does and see it is distinct from sapiens_forum and other siblings.

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

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

Gives strong intra-tool routing: participants to learn who to talk to, search_users for mention autocomplete, list defaults to 'geral'. It even says to resolve a username before sending. It does not explicitly contrast with sapiens_forum, which keeps it from 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?

Beyond the annotations, it discloses important behavior: identity always comes from sessionToken, daemons cannot post and must propose, proposals are pending and notify the human via Telegram/in-app, deletion is author-only soft-delete and idempotent, and vote re-click toggles. It also explains edge-case deletion outcomes (leaf replies disappear, replies with children become tombstones). No annotation contradiction is present.

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

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

The description is long but justified by seven sub-actions and important house rules. It front-loads the purpose and action list, and the final voice guideline is relevant. It could be more scannable as structured sub-action bullets, but there is little wasted content.

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

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

For a 14-parameter, multi-action tool with no output schema, it covers the essential workflow: action meanings, identity source, human/daemon rules, proposal approval path, deletion semantics, vote behavior, and feed/thread return hints. An agent has enough information to invoke the right sub-action 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 93%, so the schema already documents nearly all parameters. The description adds useful action-specific context such as postId for vote/delete, rootId for thread, and parentId for replies, but this largely reinforces rather than substantially extends the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the resource as a public resonance forum and enumerates seven concrete sub-actions (feed, thread, post, vote, delete, propose, proposals) with what each does. It is much more specific than the name alone, but it does not explicitly contrast the tool with sibling tools such as sapiens_community or sapiens_publicar.

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 gives clear action-level guidance, including when to use 'feed' vs 'thread', when to use 'post' vs 'propose', and why signature approval is intentionally outside the MCP. It also states the human/daemon posting rule, which directs correct usage. It does not explicitly say when to choose this tool over sibling tools, so it falls short of a full 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?

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description carries the real burden and does so richly: uploads stay private and cannot be published, publish is irreversible with no unpublish, apagar is permanent, reprovar removes a piece from all distribution paths, ingest is idempotent and capped at 12 MB image / 60 MB video / 40 per day, and the +18 stamp rules are spelled out. No contradiction with annotations.

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

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

The description is a dense, run-on wall of text with nested parentheticals and repetitions. It front-loads the basic scope, but the remaining content is not structured into scannable sections and many sentences restate schema descriptions rather than earning their place.

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

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

Given 14 sub-actions, 30 parameters, no output schema, and a mix of mutation and external-ingest behavior, the description covers edge cases and return shapes sufficiently: list returns prompt/model/url/isPublic/acervoUrl, get optionally returns base64, publish returns publicPageUrl with +18 caveats, parts returns parentage or unassembled groups. Nothing critical to correct invocation appears 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 97%, so almost all parameter meaning is already in structured fields. The description adds cross-action context and behavioral distinctions (e.g., skill filter scans last 200; link_parts order replaces prior list; refs vs processo), but most parameter-specific detail duplicates or paraphrases what the schema already says.

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 opens with a specific scope (browse, publish, upload user images) and enumerates all 14 sub-actions with distinct verbs and resources. It explicitly distinguishes itself from sapiens_image and sapiens_reference, so an agent can route gallery management here 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?

It gives explicit when-to-use rules for nearly every action: use list/get to reuse an image as a reference via sapiens_image; publish when the user wants to divulge; upload vs ingest; reprovar vs apagar; refs vs processo. Alternatives and exclusions are named, including the older-image lookup path via sapiens_reference action=browse bucket=history.

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?

Annotations say only readOnlyHint=false and openWorldHint=true, so the description carries the real burden and does it well: exact credit pricing (500 Sinapses per 1.200 chars, minimum 50), cache reads are free, repeated speech isn't re-billed, clientApiKey is rejected without charge, and the 5000-char ceiling with pre-chunking. It also discloses that output always bills in Sinapses because 'a casa não recebe chave de provedor' and that text must arrive pre-cleaned (no em-dash, no markdown). This is the kind of cost/auth/constraint context an agent needs before calling a paid, open-world tool.

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 identity and sub-actions, which is good, but it degenerates into a dense wall of run-on sentences with nested parentheses and backticked inline code. Some content is redundant with the schema (the language enum list, the 5000-char limit and pricing appear both here and in the text parameter description). Roughly a third of the text could be cut without losing meaning.

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

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

For a 14-parameter, two-action, paid TTS tool with no output schema, the description covers the essentials: what speak returns (audioBase64+mimeType+sizeBytes), billing, caching, storage behavior, and provider routing. What's thinner is failure behavior beyond the clientApiKey case and the interaction between `store` and cached responses, which is described only in the schema. Close to complete, with a few 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 coverage is 93%, so the baseline is 3; the description still adds value beyond it by stating the operational constraint that text is pre-processed by the caller and chunked above 5000 chars, and by spelling out the cost consequence of text length. It also explains the provider/model interdependency (drama-3 only meaningful for fish, native pt voices only on Gemini 3.8) that the flat schema can't express. Remaining params (outputFormat, voiceSettings, fishReferenceId) are documented only in-schema, which is acceptable at this coverage.

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: 'Helen Voice TTS via ElevenLabs, Google Gemini ou Fish Audio', and immediately enumerates the two sub-actions (list_presets, speak) with what each returns. An agent knows this is the speech-synthesis tool. It does not, however, contrast itself with nearby siblings such as sapiens_stock_audio, sapiens_musicator or sapiens_sintetico, so the differentiation work is left to the agent.

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 genuinely actionable routing between the three providers ('provider=fish ... o mais forte em japonês, mandarim e coreano: fala de personagem e cena de anime pedem ele') and between models ('modelId=drama-3 vira o Drama 3, a fala dirigida'), plus a cache/cost hint. It never states when NOT to use this tool or which sibling to pick for a non-TTS audio need. Clear context, but no explicit exclusions.

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?

Annotations only say readOnlyHint=false and openWorldHint=true; the description carries the real behavioral burden and does so richly — synchronous billing on dispatch, fixed Sinapses prices, refusal-without-charge cases ('recusa sem cobrar'), the timeout rule (gerando = already charged, don't regenerate; falhou = debit returned), compose's 25 sinapses and 10/min rate limit, and the fact that transparentBackground failures estornam. These are exactly the mutation/paid-operation traits the annotations cannot express.

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 sub-actions are front-loaded, which is right for a 10-action tool, but the block is a single dense paragraph with heavy parenthetical nesting and duplicated content — the timeout rule appears in the 'upscale' bullet and again in the closing NOTA, and the 'models' pricing caveat is restated. Much of the length is justified by complexity, but several sentences repeat rather than add.

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 33-parameter, 10-action tool with no output schema, the description covers everything needed to call it correctly: cost model and what gets billed, sync vs timeout semantics, the status-polling recovery loop, live catalog discovery for models/prices/reference limits, refund behavior, and admin-only moderation actions. Nothing essential is left for the agent to guess.

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 high (88%), so the schema already documents most fields in detail and the description largely parallels it. Where it does add value beyond the schema is cross-parameter coordination: the 5-ref global cap with per-engine truncation from supportsReferences/maxReferences, 'Mutuamente exclusivo com brandSlug' for templateSlug, and the instruction to read live values from action=models rather than hardcoding prices.

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 opens with a specific verb+resource ('Operações de imagem via Sapiens') and enumerates every sub-action (upscale, sombra, generate, compose, models, loras, status, trava, trava_julgar) with what each produces. It explicitly separates itself from siblings: 'generate=image one-shot, compose=montar start frame app-demo' and 'request_generation é legado... vídeo nasce inteiro em sapiens_video action=create', so an agent can route image work here and video work elsewhere without opening another 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 gives explicit when-to-use and when-not guidance throughout: 'models' is the catalog lookup to use 'em vez de chutar', 'status' is the required read after a Timeout ('leia action=status antes de repetir'), 'trava_julgar' is admin-only and gated on owner approval ('Só libere quando o dono, vendo a imagem, mandar'), and maskRegions requires sourceImageId with no extra refs or templateSlug. It also names the fallback path for character-lock ('o caminho é o Klein... não baixar a força'), leaving little 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?

With readOnlyHint=false the agent knows mutations exist, and the description pinpoints them: logout 'revoga a chave no servidor e apaga o token local', login persists a local session valid 90 days that auto-renews. It also discloses auth requirements (start works without login, version doesn't require login) and that action=api is strictly read-only and never returns the key or its hash. It doesn't describe rate limits or error behavior, keeping it at 4 rather than 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?

It is one unbroken paragraph dense with nested parentheses covering 13 actions, so per-action density is high but scannability is poor and the front-loaded summary is thin. Every clause carries information, yet the run-on formatting makes it harder to parse than a short bulleted mapping would 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?

For a 13-action, 4-parameter tool with no output schema, the description does substantial work: it sketches expected returns (balance/tier, plan+status+per-bucket balance with low/critical warnings, dollar balance, day spend, key names and caps) and flags which actions need login. The only real gap is that formats, health, app_url and pontes are mentioned in a phrase or not at all.

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 75%, and the description still adds meaning on top: it maps each action value to an outcome, explains that midia narrows the price table to one medium and that omitting it returns image/video/music/voice while text only appears with midia=texto, and that busca filters engine/model names accent- and case-insensitively. The code parameter's origin is only restated from the schema, but the dominant parameter (action) is fully explained.

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?

Each of the 13 actions is named with a concrete verb/outcome (start teaches connecting, login connects the account, logout revokes the key, whoami returns tier+balance+email, version reports the actually-running version), so an agent can pick an action without opening the schema. The umbrella framing ('Utilitários transversais') is vague, but it clearly separates this account/utility tool from the content-generation siblings. It stops short of 5 only because the opening line alone doesn't tell you what the tool is for.

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 concrete routing rules: use version to check whether the client picked up the new build or is stuck on npx cache, use credits/subscription before generating images to warn about overspend, use action=api for dollar balances. It also states an explicit exclusion: subscribing, moving money, changing wallet limits, enabling auto-recharge and creating keys must be done on the site, not here. No guidance on when to prefer start over login is spelled out explicitly, but it is strongly implied.

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?

Far beyond the readOnlyHint=false/openWorldHint=true annotations, the description discloses cost per action (300 Sinapses for lyrics, 3000 for render, 0 for create and publish), a rate limit (3/min on render), async fire-and-forget semantics, idempotency of publish, curation restrictions, and the owner-scoping guarantee ('só mexe nas suas tracks'). These are exactly the operational facts an agent needs before triggering a paid mutation.

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 dense paragraph, but it is front-loaded with the identity and each sub-action gets a compact parenthesized definition; nothing is filler. Some pricing detail is repeated between the prose and the model parameter description, but within the description itself 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?

For a 15-parameter, seven-action tool with no output schema, the description is remarkably complete: it covers the end-to-end flow, the async polling states, and roughly what each action returns (trackId, id/título/status/áudio). It stops short of describing failure/retry behavior on render or the exact shape of a publish response, which an agent would otherwise have to discover empirically.

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 93%, so the baseline is 3; the description earns above that by explaining cross-parameter interactions the schema only hints at — the model/durationSeconds coupling, the fixed price vs. per-duration ElevenLabs pricing, and the note that seed and negativePrompt are ignored on non-Lyria engines. The explicit pointer to the 'musica' skill for the price table is a useful addition, though a few parameters (title, context, direction) are left to the schema.

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

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

The opening line states a specific verb and resource ('loop completo de música via voz Sapiens') and the description enumerates all seven sub-actions with one-line definitions, so an agent knows exactly what the tool covers. It does not, however, name any sibling tool (e.g. sapiens_stock_audio, sapiens_trilhas) to disambiguate which one to reach for, so it stops just short of a 5.

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 gives explicit when-to-use guidance per sub-action, states the preconditions (any logged-in user for most actions; admin/owner only for publish; list_public needs no login and no cost) and spells out the intended flow: create → lyrics(trackId) → render → get (poll rendering → ready/failed) → publish. The lyrics branch even explains the two modes (with vs. without trackId) and what each produces.

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?

Adds real behavior beyond the annotations (readOnlyHint=false, openWorldHint=true): the free tier and login requirement, server-side scoring, that re-running the quiz creates a NEW profile rather than updating one, that get_quiz is static and Claude applies it conversationally, and that generate costs 450 Sinapses. That cost/state-mutation disclosure is exactly what annotations cannot convey. It omits failure modes (insufficient Sinapses, malformed answer sets) and any rate limits.

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

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

Front-loads the purpose, then organizes the rest into PRIMÁRIO/SECUNDÁRIO tiers so the free-path actions are scannable first. The final sentence listing all 16 ISO codes is pure duplication of the schema enum and does not earn its place; the dense parenthetical asides also slow parsing.

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 sketching what each action yields (48 Likert items for get_quiz, type + persona + 4-axis breakdown with confidence + history for my_profile, which arts exist for list_generated). That is enough for a six-action router. Gaps are minor: nothing on the shape of the generate response or on what happens when the profile does not yet exist.

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

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

Schema description coverage is 80%, so the schema already explains code, answers, vinculoAnswers and nome. The description reinforces the submit_quiz flow ('manda as 48 respostas {questionId,value}') and points to get_quiz as the source of question IDs, which is useful connective tissue. However, it adds no syntax or format meaning beyond the schema, and its enumeration of all 16 codes merely restates the enum.

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 concrete statement of scope (16-persona Jung-based personality test + user profile + archetype art) and then names each of the six actions with a specific verb and resource: get_quiz, submit_quiz, my_profile, list_codes, list_generated, generate. An agent can map an intent to an action without opening the schema. It loses a point because it never distinguishes itself from the sibling sapiens_profile even though 'perfil do user' / my_profile overlaps that tool's territory.

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 tiers usage: 'PRIMÁRIO (de graça, qualquer logado)' for the quiz/profile path versus 'SECUNDÁRIO' for listing and art generation, and gives a sequencing rule ('combina com "gera a arte do meu tipo" depois do quiz'). It states the pre-conditions for submit_quiz (collect all 48 answers from get_quiz first). It never says when NOT to use an action or names an alternative tool among the ~29 siblings.

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?

Annotations only say readOnlyHint=false and openWorldHint=true, which is coarse for a 17-action tool that is mostly reads; the description usefully discloses which sub-actions are LEITURA vs ESCRITA and that writes always act on the session user's own account ('identidade sempre da sessão'). It also discloses a failure return shape ({success:false,error}) for update_username and that results are derived, dated snapshots built from cheap in-prod queries ('sem custo'). It stops short of describing side effects of follow/unfollow or rate/limit behavior beyond the limit param.

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 correctly with the aggregation statement and the read/write split, but the body is a dense run-on with heavy parenthetical nesting, mixing action semantics, deprecation notes, file-saving instructions and sibling boundaries in long sentences that reward re-reading. It earns most of its length given 17 actions, but a bulleted or grouped structure would carry the same content with less parsing cost.

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, and the description does a reasonable job describing returns: 'get' as a full card, 'voz' as a dated derived snapshot under the sapiens.voz/v1 contract, error shape for update_username, and read counts for notifications. For a 17-action, 12-parameter tool it covers what an agent needs to pick and invoke an action, though the exact return shape of follow/unfollow and the favorite-list mutations is not stated.

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 92%, so the baseline is 3, but the description adds real meaning: it maps parameters to sub-actions in prose and, importantly, tells the agent where each id comes from (followingId via sapiens_community participants/search_users, toolId via sapiens_repertorio action=search_tools, listId via action=favorite_lists, notificationId from action=notifications). That cross-tool discovery guidance is not in the schema.

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

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

Opens with a specific framing ('o tudo junto do perfil do user /u/<username>, user-tier') and then enumerates exactly what it aggregates: identidade + nível/XP + saldo, badges, golden tools. It also explicitly names the boundaries against siblings (sapiens_gallery, sapiens_repertorio, sapiens_character, sapiens_persona, sapiens_meta), so an agent can distinguish it without opening other schemas.

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?

Guidance is per-action: read vs write sub-actions are grouped and labeled, 'voz' has an explicit trigger ('quando o user pedir minha voz ou meu retrato do Sapiens... chame e salve como sapiens-voz.json'), 'soul' is flagged DEPRECATED with the replacement (sapiens_sintetico action=soul), and id discovery paths are named for followingId, toolId, listId and notificationId. Exclusions are stated (large profile parts live in other tools).

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?

The description adds substantial context beyond annotations: publishing is a real, irreversible-in-the-world write to a third-party account, has no Sinapses cost but is bounded by the plan's per-cycle publication ceiling, auto-verifies results and notifies on the bell/Telegram, and cancelar only removes the scheduled time rather than deleting the piece. It also discloses the Teia behavior that child pieces wait for a click and never fire 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?

The purpose and the destructive-publishing warning are front-loaded, and every clause carries real information, but the body is a single dense run-on spanning all eight sub-actions with no structural breaks, making it hard to scan. Given the tool's surface area some length is justified, yet the lack of separation (bullets or per-action headings) costs it.

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 eight-action, 14-parameter write tool with no output schema, the description covers each sub-action's inputs, side effects, and return hints (estado por rede, link, `adaptadas`, métricas 1h/1d/7d), plus prerequisites (conexão de rede feita na tela do dashboard) and the cost model. Nothing essential to correct invocation appears 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 already 93%, so the baseline is 3, and the description adds real semantics: the block model for the legenda (text/cta/hashtags) and its truncation order, 'legendas {rede: texto}' overriding blocks per network, and the `adaptadas` return signal. The 'tiktok@2' extra-account convention and 'um envio sai por UMA conta' are echoed from the schema rather than newly added, keeping it just under a top score.

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 ('Publicar uma peça SUA nas SUAS redes') and enumerates all eleven target networks plus the account/subscription scope. It also explicitly distinguishes itself from the sibling 'sapiens_distribution' (a fila da casa é outra tool, admin), so an agent can tell the two apart without opening schemas.

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 flow ('painel com handle, escolhe pela sugestão, publicar, conferir') and defines selection conditions for each of the eight sub-actions, including the notable exclusion 'Postar de novo não tem action à parte' and the constraint 'Só peça da própria pessoa, e só rede conectada'. It escalates required caution ('Publicar POSTA DE VERDADE... confirme redes e legenda com ela antes').

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?

Beyond the readOnlyHint annotation, the description discloses important authorization behavior: resolve only succeeds for assets that are the user's or public, and it never accesses a third party's private asset. It also describes pagination and semantic search behavior, though it does not fully document all return shapes.

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 actions are front-loaded, but the description is a dense, overlong paragraph packed with detail that the schema already documents. It remains usable, but it is not tightly concise for an agent selecting and invoking the tool.

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 complex 27-parameter tool with no output schema, the description is fairly complete: it covers actions, buckets, resolve output, pagination, and normalization. Some return and edge-case details are implicit or delegated to the schema, but an agent has enough context 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 already 100%, so parameter definitions do the heavy lifting. The description still adds cross-tool meaning, such as which IDs belong in sourceImageIds versus referenceImageUrls, and what resolve returns, but much of the bucket-specific parameter detail duplicates the schema.

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

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

The description clearly defines the tool as a read-only reference browser/resolver with two sub-actions: 'browse' and 'resolve'. It explains the core resource and distinguishes public characters from a sibling tool, but does not clarify all overlapping siblings such as sapiens_stock_video.

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 gives explicit routing guidance, such as using 'resolve' for a known handle versus 'browse' for a bucket, and using the url in referenceImageUrls/startImageUrl/endImageUrl. It also points to sapiens_character action=list_public for public characters, but leaves ambiguity around related tools like sapiens_stock_video and sapiens_search.

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?

Beyond the annotations, the description discloses the permission model (any logged-in user for mutations, admin-only catalog/admin operations), deduplication by userId/source/externalId, server-side re-resolution, idempotent catalog behavior, refusal cases for mismatched admin edits, and the no-fabrication rule. These are exactly the behavioral details an agent needs and are consistent with readOnlyHint=false and openWorldHint=true.

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 front-loaded and organized by subdomain, but it is extremely dense, uses many parentheticals and all-caps warnings, and packs multiple distinct workflows into one block. Much of the length is justified by 12 actions and 35 parameters, but readability and conciseness clearly suffer.

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 12-action, 35-parameter tool with no output schema, the description covers the critical flows, preconditions, dedup behavior, and several return/refusal outcomes. It still does not explain the return shape for core reads such as list, search, get, or popArticles, leaving some output context implicit.

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 80% schema description coverage, the schema already explains most fields; the description adds important cross-field workflow meaning such as status inference ("assisti/zerei/li=completed"), person having no rating, boardgame searched by English title, links replacing the whole list, and referralUrl constraints. It does not add meaning for every parameter, such as limit, isPublic, containsSpoilers, tags, or note, so it is strong but not exhaustive.

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 opens with a precise resource ("Acervo pessoal de filme/série/anime/jogo/jogo de tabuleiro/livro/música/pessoa") and then enumerates the read actions, mutations, AI-tool flows, Sapiens/people flow, and boardgame flow. An agent can tell exactly what this tool covers and how its subdomains differ, even though it is unusually broad.

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 gives explicit when-to-use guidance for natural-language capture, AI tools ("adiciona o Midjourney"), Sapiens, and board games, and it states when admin actions are allowed ("SÓ sob ordem explícita do dono"). It also names preconditions such as running search_tools before catalog_tool, asking only when ambiguous, and not fabricating entries when resolve returns empty.

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?

This tool provides extensive behavioral details not found in structured data, such as the 'closed loop' nature (no external backend), content constraints ('jamais invente fato'), and sophisticated file handling logic distinguishing between local data URIs and remote HTTPS URLs based on the execution environment.

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?

While the description is highly informative and front-loads critical information like the business model and workflow, its sheer length and dense technical flavor prevent a perfect score in conciseness, though every sentence serves a clear purpose.

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

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

Given the complexity—handling file paths, rendering different visual themes, managing internal JSON contracts, and operating in different execution environments (stdio vs. remote)—the description provides a comprehensive, end-to-end guide for the agent.

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 description adds significant meaning to several parameters beyond their schema types. It explains the visual semantics of the 'theme' enum (e.g., jade sidebar for 'pro'), the specific local processing of 'photoPath', and the operational difference that 'outPath' facilitates for the agent.

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

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

The description clearly identifies the tool as a curriculum generator (Currículo PRO) and defines its specific operational context as being a closed, local system ('mundo fechado'). It clearly states its purpose: generating a printable HTML resume from user-provided content.

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 dictates the required interaction flow: the agent or user must first conduct the interview/paste text, construct the JSON payload, and then call the tool. It also explicitly differentiates the usage of the 'schema' and 'render' actions.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: case-insensitive substring matching, optional column/format/status/tag filters, default limit 30, and max 100. It does not describe result ordering or return fields, but the stated purpose implies finding slug/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?

The description is compact and front-loaded: search scope first, then optional filters, then defaults, then the concrete use case. Every sentence contributes new information and there is no filler or repeated schema text.

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

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

Given the 6-parameter schema with full descriptions and readOnly/openWorld annotations, the description covers the key usage context well: what fields are searched, available filters, default limit, and the intended pre-edit workflow. The main gap is that no output schema exists and the description does not explicitly state the result shape beyond the implied slug/id lookup.

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 all parameters. The description summarizes the filters and defaults, but it largely restates what the schema already provides, such as allowed values for column, format, status, and the default limit. It adds modest value by bundling the optional filters together, but not enough to exceed the baseline.

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

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

The description starts with a specific verb and resource: 'Busca substring case-insensitive em title/excerpt/tldr/slug/tags dos artigos.' It clearly identifies the search scope over article fields and differentiates itself from siblings by framing this as the tool to find existing article slug/id before editing, publishing, or deleting via sapiens_article.

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

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

The description explicitly states when to use this tool: 'Use pra achar slug/id de artigo pré-existente antes de editar/publicar/deletar via sapiens_article.' This names the related tool sapiens_article and the workflow condition, making the choice between search and article operations clear.

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?

Goes well beyond the sparse annotations: it discloses idempotency of 'fechar', that the tool pays XP rather than charging Sinapses, and the full scoring model (step thresholds, diminishing returns, width bonuses). This is exactly the mutation/side-effect context annotations (readOnlyHint=false) do not provide on their own.

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 is front-loaded, but the 'get' sub-action is delivered as one very long parenthetical enumerating seven separate outputs and the scoring rules that follow are dense prose. Every piece is relevant, yet the structure makes it hard to scan and could have been broken into a list.

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, and the description outlines returns for both actions in detail (pieces per activity, XP paid, Casa Cheia projection, streaks, prior weeks). For a one-parameter enum tool this 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 0%, but with a single enum parameter the description fully compensates by explaining what 'get' returns and what 'fechar' does. An agent can choose the correct action value from the description alone.

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: weekly house activities, what you produced and how much XP it yielded, with identity via sessionToken. It clearly delimits the XP/weekly domain. It does not explicitly differentiate itself from any of the many sapiens_* siblings, so it stops short of a 5.

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?

Both sub-actions are spelled out ('get' reads the week, 'fechar' closes pending weeks and credits Casa Cheia), and it explicitly notes 'Esta tool PAGA XP, não cobra Sinapses', which tells an agent what this tool is not for. No comparison to sibling tools is offered, so 4 rather than 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?

Beyond the annotations, it discloses costs and refunds (send spends Sinapses, reflexo_generate charges 450 and refunds on failure), rate limits (10k/day and 3 sends/day, log caps), idempotency via transferId, admin-only gates, and silent logging behavior. These are consistent with readOnlyHint=false and openWorldHint=true; no contradiction is present.

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 information is front-loaded with the core purpose and action names, and much of the length is justified by 20 actions. However, it is a dense run-on paragraph with flavor text and semicolon-separated clauses, making it harder to scan than a structured action list would 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?

For a 21-parameter, 20-action tool with no output schema, the description covers the key operational context: what each action does, prerequisites, costs, limits, web-only exclusions, and partial return meanings such as status, bonds, sonda hooks, and soul output. Nothing critical for correct invocation appears 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 95%, so most parameter-level meaning is already documented. The description still adds essential semantics for the required action enum, whose 20 values are not explained in the schema, plus cross-parameter workflow guidance such as getting toUserId from status/bonds and using characterId from sapiens_character list_mine.

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 resource and relationship: the human↔Synthetic link (Sintonia) via MCP, and enumerates the sub-actions it exposes. It distinguishes some sibling boundaries, such as using sapiens_character for authored characters and sapiens_profile for the person's voice, but the tool's broad action set is not contrasted against every sibling in one clear scope statement.

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 gives explicit when-to-use guidance per action, including calling send_context before send, using companion mode on/off, and that accepting bond requests or consecrating a Reflexo remain web-only. It also names alternatives and exclusions: authored characters via characterId, other people's characters only through the site DM, and sapiens_profile for the person's own voice.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with 'sem login, sem custo, sem rede' plus 'grátis' for list — real context about auth and cost. It also discloses an alternate access path (skill://sapiens/<slug>/SKILL.md as an MCP resource), though it says little about size/length of the returned SKILL.md.

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 the read-before-operating directive, then sub-actions, then the slug index. The long pipe-delimited slug list is dense but functional; the closing resource note is arguably redundant with the earlier 'servido pelo próprio connector' framing.

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 optional parameters and no output schema, the description fully covers what each action returns (index of slug + when-to-use; the full SKILL.md) and offers an equivalent resource route. 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%, so baseline is 3, but the description adds genuine meaning by enumerating the complete valid slug set and the name=<slug> pairing for 'get', whereas the schema only offers three examples. It does not explain slug aliasing or error behavior for an unknown slug.

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 resource (the SKILLS/step-by-step docs of each Sapiens flow) and the two operations ('list' index, 'get' full SKILL.md), and explicitly frames itself as served by the connector rather than being an operational tool. This clearly separates it from the 29 sibling tools, which all perform flows rather than document them.

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

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

Gives an explicit directive — read the skill BEFORE operating the flow — plus the cost rationale (cheaper than a bad generation that charges Sinapses), and routes the agent to action='list' when the slug is unknown. When-to-use, why, and the fallback path are all stated.

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?

Annotations are minimal (readOnlyHint=false, openWorldHint=true), so the description carries real weight and delivers: per-provider pricing with minimums, async polling contract (generate → generation-status until 'ready'/'failed'), refund behavior on failure, and the privacy rule that scenes stay with the author and do not enter the shared acervo. It also notes generated effects do enter the acervo as kind=sfx. Docked one point because the list/get return shape is only partly disclosed (count/items, title/url/durationSeconds) and pagination behavior is unaddressed.

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?

Dense and front-loaded: the bank definition and the free read actions come first, paid generation and scene follow. Every clause carries information — no filler. The weakness is structure: a single unbroken wall of prose across seven actions and 20 parameters that would scan far better as a short bulleted action map, which raises the risk of an agent skimming past the scene/status pairing.

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 7-action, 20-parameter tool with no output schema, the description covers everything an agent needs to call it correctly: which actions are free vs. paid, the async completion pattern for both long-running actions, failure/refund semantics, result usage, and the sibling handoff for music. The explicit privacy note on scenes is a detail an agent could not infer from any structured field.

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 coordination the schema cannot: the generate→generation-status(generationId)→ready(audioUrl) loop, the cost-escalation-by-second model, and the practical instruction to take the returned `url` straight into ffmpeg. It also disambiguates durationSeconds per action and confines promptInfluence to provider='elevenlabs'. Mostly additive, though several details (provider pricing, mood enum, pitch/speech rates) are duplicated from the schema.

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

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

States a specific resource (banco de som da casa: trilha pronta + efeito sonoro) and enumerates each sub-action with its own verb and output (categories lists moods, list searches with filters, get returns 1 item by audioId). It also draws the boundary against siblings: new music/trilha goes to sapiens_musicator, and scene/generate are named as distinct write actions. An agent can pick the right action 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 routing: read actions are declared 'públicas, sem auth', while generate and scene are flagged 'COBRA Sinapses, exige login'. It gives the escalation path verbatim — 'Não achou o efeito? generate' — and hands off music generation to sapiens_musicator. When-not-to-use is stated for the short-effect limit (1-15s) versus full tracks.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: 'Leitura pública, sem auth' (auth need) and the return shape {count, items} with the item fields (title/url/posterUrl/durationSeconds/orientation/loopFriendly/tags). It does not discuss rate limits or pagination behavior, so not 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?

Front-loaded with the resource and sub-actions, and every clause carries information about use or parameters. It is dense and somewhat run-on within a single long sentence with parenthetical lists, which costs a little readability, but there is little wasted text.

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

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

For a 9-param, 3-action tool with no output schema, the description covers the list return fields and the per-action intent well, and even the categories return content (moods/usos). The only minor gap is the exact return shape of get by videoId, which is left implicit.

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 would be 3, but the description adds real meaning beyond the schema: it lists the concrete mood categories, maps orientation to aspect ratios with intent (vertical=9:16 for shorts, horizontal=16:9), and explains loopOnly='fundo que repete limpo'. That is additive value over the already-complete schema.

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

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

States a specific resource (stock clip/B-roll catalog ready on CDN, downloadable, free/internal) and enumerates the three sub-actions (categories/list/get) with what each returns. It explicitly distinguishes itself from the sibling sapiens_video by positioning itself as ready-made B-roll rather than generation.

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: 'Use pra puxar B-roll pronto em vez de gerar via sapiens_video', naming the alternative and the condition. It then gives concrete use cases (page background/atmosphere, B-roll in the /sapiens:movie ffmpeg pipeline, first/last frame) and hints at orientation/loopOnly choice for shorts vs page backgrounds.

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 readOnlyHint=false and openWorldHint=true already declared, the description adds real context beyond the annotations: create publishes immediately with a public address, has no draft state, is free, and is capped per person. However, that cap is stated as 'teto de 8 por pessoa' in the description while the schema says 'Teto de 4 por pessoa' — a factual inconsistency that weakens trust in the behavioral claims.

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 definition is front-loaded: identity of the resource first, then the action list, then usage triggers, then the covered studios. Dense but each clause carries information. Minor redundancy between the description's action summary and the action enum's own descriptions 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?

For a five-action multiplexed tool with no output schema, the description covers what each action yields and how create behaves. What an agent still lacks is anything about failure modes (e.g. hitting the studio cap, invalid slug) and the 8-vs-4 quota conflict leaves one rule ambiguous.

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 which action each applies to. The description restates the action set but adds no syntax, format, or constraint details beyond the structured fields (and, for the quota, actively conflicts). Baseline 3 is correct here.

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 resource (the user's company studio plus the Sapiens studio/experiment catalog) and enumerates all five sub-actions with what each returns (mine = name/public address/brand/operator/team size; list = URL+status+tags+mcpReady; get = one slug; publishable_url = /articles/<slug>). It also names the covered studios, so an agent can distinguish it from siblings like sapiens_brand or sapiens_gallery 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 gives explicit trigger phrases in both directions, in Portuguese: use when the user asks 'que estúdios existem' / 'qual o meu studio', or says 'quero abrir/fundar meu studio'. That is strong when-to-use guidance. It does not name alternatives or exclusions (e.g. that brand edits go to sapiens_brand rather than here), which keeps it short of 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?

Beyond the sparse annotations, the description discloses authentication via sessionToken, enforced per-user scope, the PII-leak rationale, that replies re-open closed tickets, and which operations are server-side. This is rich behavioral context with no contradiction to readOnlyHint=false or openWorldHint=true.

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 dense but not wasteful. Scope and security are front-loaded, the sub-actions are compressed into one readable list, and the outside-of-MCP note prevents misuse without extra sentences.

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 having no output schema, the description covers return values (ticketId, message history, status/data), input constraints, authentication identity, and unsupported operations. It is complete enough for an agent to select and call the tool 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 high (83%), but the description adds essential conditional semantics: subject is mandatory for create, message/whatsapp are optional, ticketId comes from list, and content is the reply text. It resolves the action-dependent parameter meanings that the flat schema alone cannot express.

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

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

The description clearly names the resource (support tickets), the actor scope (the user's own tickets only), and enumerates the four sub-actions. This makes it easy to distinguish from the content-oriented sibling tools.

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?

Each sub-action has explicit triggers and expected results, and the description clearly states what is not possible ('Fechar/escalar/deletar ficam no lado do suporte, fora do MCP'). It also strictly warns against touching other people's tickets, giving clear when/when-not guidance.

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?

Adds real context beyond annotations: identity is always via sessionToken, and claim_mission only submits for owner review — Sinapses credit lands only on approval, never auto-credited. This clarifies the mutation semantics that readOnlyHint=false alone cannot convey. Doesn't cover rate limits or failure modes.

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 domain and identity rule, then sub-actions, then the critical no-auto-credit caveat, then the flow recap. Dense but every sentence carries information; only the final flow line partly repeats earlier content.

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

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

With no output schema, the description carries return-value burden and does it well — titles, module/lesson counts, per-challenge status enum, reward, action link. What's missing is what claim_mission returns and any error/validation behavior.

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 75%, but the description adds provenance the schema lacks: slug comes from 'list', missionId comes from 'list_challenges', and proofText is what the owner will review. That cross-references the workflow, not just restating field 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 the resource (Trilhas/cursos and Desafios/missões da Sapiens) and enumerates the four sub-actions with what each returns. An agent can distinguish this from all 28 sibling tools 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 flow guidance: 'list → get' and 'list_challenges → claim_mission', plus where each ID originates. No explicit when-not or named alternative, but no sibling overlaps the courses/challenges domain, so the guidance is essentially complete.

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?

Annotations only supply readOnlyHint=false and openWorldHint=true; the description adds the full behavioral picture: create is asynchronous and returns immediately with {imageId, status:'rendering', cost}, provider failures refund automatically, omitted resolution/durationSec silently bills the most expensive tier ('Um create de Seedance 2.0 sem resolution debita 1080p'), and synchronous edit actions can exceed 2 minutes so a timeout is the client giving up. It also discloses auth/ownership constraints (only your own gallery items, Spicy refuses externally supplied stills) and admin-only actions.

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 content is load-bearing, but the delivery is a single undifferentiated block with multi-level nested parentheses (the Omni 1.2 entry nests a parenthetical about the four retired Google models inside the model catalogue inside the sub-action list). Model specs, pricing rules, frame rules, editing actions, admin film actions and caption pricing all compete in one paragraph with no headings. A far shorter version could front-load create/price/status and push the per-model catalogue into action=models, which the description itself says is the live source.

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 55-parameter, 27-action tool with no output schema, the description covers everything an agent needs to call it correctly: required action, the async create→status loop, the exact return shape {imageId, status, cost}, cost/quota behavior, and refusal semantics per model family. No material gap remains; the problem is volume and organization, not missing information.

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 98%, so 3 is the floor and the schema already documents most params. The description still adds meaning the schema can't carry well: cross-parameter exclusivity ('Referência e frame de borda são EXCLUSIVOS no H3 e na linha Seedance 2.0'), the cost consequence of omitting resolution or durationSec, and the storyboard workflow linking referenceImageIds with sapiens_image templateSlug='storyboard-sapiens-v1'. That is real semantic value above the field-level 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?

The opening states a specific verb and resource explicitly: 'gera vídeo (qualquer membro logado; vídeo é caro, cobra as Sinapses da sua conta)' and immediately names the recommended sub-action 'create'. It goes further by naming siblings and historical replacements ('Isto substitui a tool sapiens_shorts'), which separates it from sapiens_image and sapiens_gallery. It loses a point only because the model-by-model catalogue buries the core purpose under thousands of words.

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

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

The description explicitly routes between alternatives: 'Use o Mini pra iterar enquadramento/prompt barato e feche no sapiens-video-seedance quando o take estiver certo', and 'Quem precisa de 1080p fica no sapiens-video-seedance'. It also states when NOT to act ('NÃO chame create de novo enquanto renderiza (cria outro vídeo e cobra de novo)') and points to action=price and action=models before spending. This is explicit when/when-not/alternatives coverage.

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?

Annotations (readOnlyHint=false, openWorldHint=true) establish this is a mutating open-world tool; the description adds substantial context beyond that: cost (400 Sinapses, refunded on failure), synchronous execution under a timeout rule, and no idempotency (blind retry creates a second draft and double charges). However, several write behaviors (what update replaces, whether publish changes URL) are only implied. Strong added value, so a 3+ rather than higher.

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?

Dense but front-loaded: the port-choice decision (create vs generate) comes before action details, which is the highest-value information. It is long and partially restates schema descriptions (coverImageId, brandSlug), costing it the top mark, but every sentence carries routing or cost 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 21-parameter, six-action tool with no output schema, the description covers all actions, cost model, identity/sessionToken, timeout behavior, and cross-tool dependencies (sapiens_image, sapiens_brand, sapiens_gallery, sapiens_repertorio). 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 86%, so the schema already carries most parameter meaning (baseline 3). The description adds the 'why' for key params: brandSlug controls whose design system styles the cover/images, and coverImageId/coverImageUrl override the courtesy cover when an image already exists. Marginal but real value above the schema.

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

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

States a specific verb+resource and scope: user's own self-serve articles at /u/<username>, explicitly NOT the editorial blog. It names the sibling it is not (sapiens_article for the curated editorial blog) and enumerates all six sub-actions, so an agent can tell exactly what it does.

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 guidance: text the person already wrote goes to create (free), AI only in generate (400 Sinapses), and burning 400 by generating then overwriting is called out as a mistake. It also names the alternative (sapiens_article) and gives a timeout/idempotency warning with the prescribed check (action=list before retrying).

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