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

The description adds significant behavioral context beyond the annotations: delete is 'irreversível', update 'NÃO toca status/column/format', ensure_visuals is idempotent and costs ~1700 Sinapses on an empty article, and bodyImages replaces the full set rather than merging. This goes well beyond the readOnlyHint/openWorldHint 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 dense but every clause earns its place: it names the core CRUD capability, enumerates each sub-action with key caveats, and closes with creation alternatives. It is front-loaded with the most important scope statement and avoids filler.

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

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

For a 26-parameter multimodal CRUD tool with no output schema, the description covers the operational essentials: required identifiers, action semantics, destructive consequences, idempotence, cost, visual replacement behavior, and alternative routing for creation. Combined with the schema, an agent has enough context to select and invoke it correctly.

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

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

Schema description coverage is low (42%), and the description compensates well for the most complex parameters: it explains slug for get, articleId discoverability, visual fields for update, and force flags for ensure_visuals. It relies on natural-language field names for fields like category, tags, and connectedSlugs, which are self-evident, but it does not explicitly cover every parameter.

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 'CRUD direto de artigos do blog Sapiens' and then enumerates all sub-actions: get, update, publish, unpublish, delete, and ensure_visuals. It clearly distinguishes this tool from creation tools by explicitly directing new-article creation to sapiens_quote_pop or 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 provides explicit when-to-use guidance per action, names alternatives for article creation ('Pra criar artigo novo use sapiens_quote_pop... ou sapiens_pipeline'), and even explains when to use ensure_visuals versus manual visual replacement. No meaningful usage ambiguity remains.

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 the description reinforces this by saying 'READ-ONLY' and 'Nenhuma escrita'. It adds substantial behavioral context beyond annotations: the tool is locked to the paid Lens, identity always comes from sessionToken, unauthorized users get only an acquisition notice, and each sub-action returns a specific kind of curated 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?

The description is dense but well organized: constraints and access model are front-loaded, then each sub-action is given a compact parenthetical summary, and the closing sentence restates the no-write boundary. Nothing feels redundant for a four-action 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 the four sub-actions, an access gate, and no output schema, the description covers the essentials: what each action returns, optional filters, and behavior for unauthorized users. An agent has enough to select and invoke the correct action.

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 75% schema coverage, the schema already documents limit, ticker, and authorHandle, and the action enum. The description adds value by explaining what each action surfaces (e.g., overview maps ~52 curated companies with market cap and industry; signals are recent X posts with optional ticker/author filters). It does not add much beyond the schema for limit, but the action-level context is genuinely useful.

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 a consult/read-only resource: 'Atlas Ecossistema IA' with curated AI value-chain data, listing four sub-actions so an agent knows exactly what it offers. It doesn't explicitly contrast against sibling tools like sapiens_search beyond saying 'Nenhuma escrita', so it stops just short of full sibling differentiation.

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 context for when to use the tool: to inform oneself and answer questions on curated ecosystem data, and it warns that users without the paid Lente receive an acquisition notice and no data. It does not explicitly name alternative tools or say when not to use it, so no exclusions are provided.

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 (readOnlyHint=false, openWorldHint=true), the description discloses server-side behaviors: voice re-linting producing voiceWarnings, on-demand serving via /aulas/<slug> without rebuild, and admin restriction semantics ('aluno leva restrito ao dono'). These details meaningfully extend what annotations alone provide and do not contradict them.

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 bloated; every sentence carries necessary information and the core purpose is front-loaded before sub-action details. However, it is a single long paragraph without visual separation (bullets/line breaks), which slightly hurts scannability for an agent.

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 tool with three sub-actions and no output schema, the description covers the required input structure, slide type taxonomy, voice constraints, and route behavior. The main gap is that the upsert response/return value is not specified, though list fields and get's 'aula completa' output are hinted.

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

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

Schema coverage is 67% (aula and slug have descriptions; action does not), and the description compensates by explaining the action enum's behavior, slug kebab-case format, and the upsert semantics (create-if-missing vs patch). It adds real meaning beyond the schema, though it partly repeats the schema's already-detailed aula structure.

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 states the tool's purpose: 'Cria e edita aula direto no Convex' and enumerates its sub-actions (list, get, upsert), making the verb+resource explicit. However, it does not explicitly differentiate from sibling sapiens_* tools, only from the external migrate script, so it stops short of the full sibling-distinguishing criterion.

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 gives explicit when-to-use guidance per sub-action, states that it replaces the migrate-aulas-to-convex.mjs script, and declares the ADMIN-ONLY constraint, including the student case. This is strong, actionable usage guidance with a named alternative and exclusion conditions.

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 (readOnlyHint=false, openWorldHint=true), the description discloses costs (~950 Sinapses for generate with refund on failure, ~75 for refine, free reroll, catalog model price for card), billing from the sessionToken owner, visibility/publication effects, and persona dropping on adopt. This gives the agent important side-effect awareness.

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 and front-loaded with the core definition, then organized around sub-actions; the length is justified by ten distinct behaviors. It is slightly run-on and repeats the generate cost warning at the end, but every section carries operational value.

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 covers each action's purpose, applicable parameters, auth requirement, costs, and side effects. The agent can correctly select and invoke any sub-action, and the workflow hint for generate fills the main open-ended parameter.

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?

Input schema coverage is high (89%) and already documents parameter purposes, so the description doesn't need to re-explain them. It adds value by mapping params to specific actions (slug for get/refine/reroll/card/delete/set_visibility/adopt, piece for reroll, feedback examples, isPublic semantics) and by giving workflow guidance for generate's description parameter.

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 by defining Brand Sapiens as a Design System (palette, typography, voice, image style, persona) and as the single source of style, then itemizes ten concrete sub-actions (list, get, generate, refine, reroll, card, delete, set_visibility, list_public, adopt) with distinct verbs and resources. This clearly distinguishes it from related content-generation siblings and from its own sub-actions.

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 states when each sub-action applies and attaches conditions: get is 'só oficial ou o próprio', delete/set_visibility apply to the user's custom brands, list_public is for community opt-in public designs, and adopt clones into a new private copy while dropping persona. For generate it instructs the agent to converse with the user, assemble a rich description, and confirm the ~950 Sinapse cost before calling.

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 carry readOnlyHint=false and openWorldHint=true, so the description carries nearly the full burden. It discloses destructive behavior (delete is permanent), preconditions (activate requires ≥1 image), side effects (first image becomes main; public visibility generates a slug), and ownership constraints. 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 description is dense but every sentence earns its place: it covers 12 sub-actions, preconditions, and integration points. However, the content is a single run-on block with semicolon-separated clauses; grouping the image-management actions helps, but bullet structure would make it more scannable for an agent.

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 tool with 12 parameters, no output schema, and minimal annotations, the description is remarkably complete. It explains auth/ownership, public vs draft/private behavior, required image before activation, retrieval of current imageUrls, deletion permanence, and how to use outputs like mainImageUrl downstream. No essential information is missing.

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

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

The input schema already covers 92% of parameter descriptions, so the description does not need to compensate. It adds useful action-to-parameter context, such as which parameter applies to which action, but most of this is either restated from the schema or is tool-level workflow context rather than new parameter-level detail.

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 (`influencers` character sheets), what it does (reusable characters with images and system prompts), and enumerates every sub-action. It also distinguishes the tool from image generation tools by explaining how character images are consumed by sapiens_image.

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 provides explicit usage rules per sub-action: list_public for the public catalog, get for details, list_mine for own characters, and the ownership/visibility restrictions. It also gives an end-to-end creation flow (create → add_image → set_card → activate → set_visibility) and tells the agent exactly how to use a public character as a reference in sapiens_image.

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 goes well beyond the annotations, disclosing important side effects: Claude posts as the user's intercessor, the server appends '· via Claude', react is a toggle, mentions notify via bell and Telegram, media ownership is verified server-side, and asTese creates a branded, forum-pingable card. These details are consistent with readOnlyHint=false and give the agent an accurate mental model of the tool's effects.

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 and every clause contributes useful information. It could be more scannable with bullets or subheadings for each sub-action, but it remains efficient and front-loaded with the core 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?

For a complex tool with five sub-actions and no output schema, the description covers all major aspects: action selection, mention protocol, asset attachment, TESE behavior, and editorial voice. It even describes expected outputs for participants and search_users, leaving little ambiguity for an agent deciding how to invoke it.

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?

Even with 91% schema coverage, the description adds meaning beyond the schema: it explains how action selects a sub-behavior, how mediaAssetKind/mediaAssetId compose an asset card, how asTese changes the post type, and how query/search_users support mention autocomplete. This integration-level semantics is exactly what the agent needs beyond raw parameter names.

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 the Sapiens community chat for subscribers/alumni and enumerates five concrete sub-actions (list, send, react, participants, search_users), each with a specific resource and behavior. This makes it readily distinguishable from siblings like sapiens_forum, even without an explicit contrast.

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 provides strong context for when to use the tool and strong intra-tool routing guidance, such as using participants/search_users to discover the correct @username before sending and using react for emoji toggling. However, it does not explicitly explain when this tool should be preferred over alternatives like sapiens_forum or when it should not be used.

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 far beyond the sparse annotations by disclosing soft-delete and tombstone behavior, vote cancellation/switching, daemon rejection and re-routing to proposals, human notification on propose, and the feed item shape. No annotation contradiction: readOnlyHint=false aligns with the described mutating 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?

Dense but purposeful; the core concept is front-loaded, followed by house rules and a sub-action catalog. Length is justified for a 7-action tool, though a single wall of text would benefit from bullet or paragraph separation.

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

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

Covers all seven actions, return-shape hints (feed items carry _id, author, counters, user's vote), the signing handoff, media rules, and the Sapiens voice constraint. Since there is no output schema, the description itself supplies enough of the behavioral contract for an agent to 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 description coverage is 93%, so the schema already documents parameters and the baseline is 3. The description adds action-specific meaning above that: parentId omission opens a new thread, postId is dual-purpose for vote/delete, mediaTrackId ownership is validated by the server, and mediaUrl is restricted to house media.

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 ('Fórum de Ressonância', public forum), defines its core objects (tese/vote/feed), and enumerates all seven sub-actions with specific semantics. Its scope is unmistakable even among the many sapiens_* 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?

Explicitly sets when/when-not rules: humans post directly, daemons must propose instead of posting, signing is deliberately outside the MCP, deletes are limited to the author's own theses, and votes toggle/switch. It even names the alternative signing channels (web dashboard and Telegram).

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 discloses significant side effects beyond the annotations: publish makes the image appear in the public gallery and Pinterest feed, can create an indexable /imagem/<id> page, and returns publicPageUrl; unpublish reverts it to private. It also warns that includeBase64 is heavy, which helps the agent avoid expensive calls. No contradiction with annotations was found.

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 and packed with useful information, but it is written as a long uninterrupted paragraph in Portuguese. A more structured layout with sub-action bullets would improve scannability; nevertheless, every sentence contributes meaningful guidance.

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 there is no output schema, the description compensates by explaining return behavior for list, get, and publish, and by describing the effects of unpublish. It also cross-references how to use the returned imageId with sapiens_image, making the tool actionable in its full workflow.

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?

Even though the schema already covers 80% of parameters, the description adds important meaning: it ties limit to 'latest N images', describes list result fields (prompt/model/url + isPublic), clarifies that imageId is required for get/publish/unpublish, and explains what publish returns. This significantly aids correct parameter usage.

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 managing the user's generated images, then defines four specific sub-actions (list, get, publish, unpublish) with distinct outcomes. This makes the tool's scope and each operation immediately recognizable, even distinguishing it from related tools like sapiens_image.

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 tells the agent when to use list/get (to reuse an image as reference via sapiens_image, or to show the user what they have) and when to use publish (when the user wants to make their image public). This goes beyond generic hints and provides a decision rule.

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, so the description carries the burden of explaining side effects. It does this richly: it mentions charging, external providers, BYOK vs env keys, chunking before 5000 chars, and required caller-side preprocessing. This is substantial behavioral disclosure beyond the structured metadata.

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 efficient, covering purpose, sub-actions, output, cost, BYOK, limits, and preprocessing in a compact paragraph. It front-loads the core purpose and avoids redundant restatements, though the density makes it slightly harder to scan than a bulleted structure 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?

Given 11 parameters, a nested voiceSettings object, and no output schema, the description covers the essential missing pieces: return shape, sub-action behavior, provider cost, and text constraints. It lacks details on error handling or provider-specific edge cases, but those are not necessary for basic correct invocation.

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 (91%), so the baseline is 3. The description adds value beyond the schema by explaining the meaning of 'action' sub-actions, the output fields for 'speak', the chunking constraint tied to 'text', and the cost model tied to 'provider'. This is more than the schema provides 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?

The description clearly states the tool is a TTS tool ('Helen Voice TTS') and spells out its two sub-actions ('list_presets' and 'speak'), along with the output form ('audioBase64+mimeType+sizeBytes'). It is specific about providers and scope, though it does not explicitly differentiate itself from sibling tools, 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?

The description gives clear operational context: who can use it ('qualquer logado'), costing implications ('cobra Sinapses'), BYOK behavior, the 5000-character limit, and the required preprocessing of 'text'. It does not explicitly name alternatives or when-not-to-use conditions, but the provider and sub-action guidance is clear enough for practical selection.

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 discloses major behavioral traits beyond the sparse annotations: generate is synchronous and charges on completion, heavy models are subject to timeout, request_generation debits credits and creates only a pending row with rate limits, and compose has synapse/rate limits. It even warns to check sapiens_gallery before retrying to avoid double charging.

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 the tool is complex with 23 parameters and four sub-actions. It uses labeled blocks and dense semicolon-separated facts effectively. There is some redundancy, such as the 'generate=image one-shot, request_generation=criar row video, compose=montar start frame app-demo' recap, but most sentences carry operational value.

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

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

The description covers invocation prerequisites, rate limits, costs, timeout handling, and where to verify results via sapiens_gallery. With no output schema, explicit return shapes for each action are not fully described, though schema-level parameter notes partially compensate by mentioning fields like studioApplied.

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 83%, so the baseline is 3. The description adds meaningful cross-parameter semantics: multi-reference limits combining referenceImageUrls and sourceImageIds, model-specific reference support, templateSlug/brandSlug mutual exclusivity, and template behavior that turns prompt into scene-only input. It doesn't explain a few lower-level params like negativePrompt and MIME-type fields, but the added value is solid.

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 by defining the tool's scope (image operations via Sapiens) and then enumerates four sub-actions with distinct verbs: generate, request_generation, compose, and models. It also distinguishes these from video-oriented siblings by explicitly referencing sapiens_shorts/sapiens_video for the request_generation path.

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 states when to use each sub-action: request_generation is for sapiens-video-* models before sapiens_shorts/sapiens_video, generate is the one-shot image path, compose builds the Shorts app-demo start frame, and models discovers live pricing/capabilities instead of guessing. This gives clear routing among alternatives.

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 readOnlyHint=false and openWorldHint=true, and the description is fully consistent with those. It discloses mutation effects (cria/edita, apaga, responde na mão), permissions (ADMIN-ONLY), API limits (Meta refuses outside the 24h window), and algorithmic behaviors such as round-robin variants and the fallback rule firing only 1x/24h per person. This goes well beyond what the annotations alone communicate.

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 with purpose and the admin gate, and every clause contributes to one of the seven actions or the API constraints. However, it is a long, dense run-on paragraph (roughly 250 words) that mixes action semantics, parameter rules, and limitations; better separation would improve scannability. The length is defensible given the 17-parameter/7-action surface.

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, yet the description covers output-oriented details for key actions, such as posts returning id+caption+thumb and inbox conversations exposing canReply based on the Meta window. It also covers required parameter combinations, ID provenance, API restrictions, and edge-case caveats like fallback not firing on comments. For a complex tool, this is a complete enough description for an agent to select and invoke the correct action.

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 94%, and the description still adds valuable cross-parameter semantics: keyword+reply are mandatory outside fallback, matchMode and trigger values are explained, mediaId scopes a rule to a post and tells the agent to get real IDs via action=posts, and igUserId comes from inbox. It also clarifies behavioral effects like replyVariants/echoVariants round-robin and fallback never firing on comments, which the schema alone does not 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 names a specific resource and operation: the Instagram auto-DM engine ('ManyChat próprio') for @sapiensinteticos, and says 'aqui você OPERA esse motor.' It enumerates seven sub-actions (rules, rule_upsert, rule_delete, posts, inbox, thread, send), so an agent can clearly identify what the tool does. This strongly differentiates it from the many sapiens_* sibling tools by resource and action space.

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 states 'ADMIN-ONLY (dono)' and defines the operating context: when DMs or keyword comments arrive, this tool operates the automation engine. It gives concrete workflow hints such as 'pegue ids reais com action=posts' and 'vem do inbox', plus an explicit exclusion: 'não dá pra iniciar conversa, só reagir; janela de 24h pra responder DM.' It does not name alternative siblings, but the action-level routing is strong enough for this domain.

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 discloses behavioral details beyond annotations: login saves a 30-day local session, version does not require login, start behaves differently depending on login state, and subscription emits low/critical warnings. Annotations only provide readOnlyHint=false and openWorldHint=true, so the description carries the burden and does it well.

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 dense and every phrase adds value, but it is structured as one long run-on paragraph with deep parentheses, making it harder to parse. A bulleted list or per-action sentences would improve scannability. It is informative but not concise in format.

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

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

With no output schema, the description compensates by explaining the key outputs for whoami, subscription, health, and version, and by giving usage warnings for quota checks. A few actions like logout, formats, and app_url are only briefly named, but their behavior is fairly self-evident given the overall utility context.

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 both parameters. It explains what each action enum value does, and it clarifies the code parameter format (XXXX-XXXX) and when it applies (action=login). The schema itself only documents code with a short note and lists enum values, so the description fully compensates for the 50% 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 clearly identifies the tool as transversal utilities and enumerates each action (start, login, logout, whoami, credits, subscription, formats, health, version, app_url) with a specific purpose. It does not explicitly contrast with sibling tools, but the action-level detail differentiates it from the content-generation 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?

The description provides concrete usage timing: use credits/subscription before generating images to warn about quota exhaustion, and use version to detect whether the client is stuck with cached npx code. It does not explicitly state when not to use the tool or name alternative tools, but the meta/utility nature is clear from the action list.

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 (readOnlyHint=false, openWorldHint=true), the description discloses per-action costs, render's fire-and-forget async behavior, publish's side effects echoing to Chat and Fórum, owner scoping, and the rendering status lifecycle. This is rich behavioral context with no contradiction against 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 dense but organized: overview, sub-action list with costs and effects, then the recommended flow and ownership scope. The length is justified by seven sub-actions and several operational details, though the opening sentence mixes cost data into the overview, making it slightly less scannable than it could be with a more structured layout.

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 of 13 parameters, seven sub-actions, and no output schema, the description covers the full lifecycle, permissions, costs, side effects, and enough return hints (trackId, list fields, get fields) for an agent to call and sequence the tool correctly. Nothing essential for selection or invocation is missing.

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

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

Schema description coverage is 92%, so the baseline is already 3. The description adds action-level semantic meaning: trackId is required for render/get but optional and persistence-oriented for lyrics, create returns a trackId at zero cost, and list returns track metadata including status and audio. This goes beyond the schema's per-parameter descriptions without repeating all thirteen parameters.

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 tool as a complete music loop via Sapiens voice without requiring the UI, and immediately enumerates seven concrete sub-actions (create, lyrics, list, get, render, publish, list_public). This is a specific verb+resource framing that clearly differentiates it from the broader sapiens_* siblings like stock audio, studios, or video 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?

The description provides an explicit full workflow: create → lyrics(trackId) → render → get → publish, and gives per-action conditions such as render being asynchronous fire-and-forget, publish being curated and idempotent, and list_public requiring no login. It lacks an explicit 'when not to use' sibling comparison, but inside this multi-action tool the routing guidance is strong.

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 discloses state-changing behavior, 'salva no perfil; refazer cria profile novo,' and cost, '450 Sinapses,' plus which operations are static. It does not contradict the readOnlyHint:false annotation; it actually explains the mutating actions well.

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 with the product purpose and organized by PRIMÁRIO/SECUNDÁRIO, making it scannable. Each action clause earns its place. The final enumeration of all 16 codes duplicates the schema enum and adds length, so it is not 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?

Despite having no output schema, the description covers the return or effect of every action: my_profile's breakdown and history, list_generated's existing art, generate's archetype art, and get_quiz's 48 questions. It also specifies sequence requirements and the cost of generate, making the tool complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 80%, so the baseline is 3. The description adds useful action-level semantics like the 48-question Likert 1..7 scale, NT/NF/SJ/SP code groups, and server-side scoring. Much of the per-parameter meaning already lives in the input schema, but the description enriches it beyond that 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 opens by naming the exact domain and resource: 'quiz MBTI + perfil do user + arte dos 16 arquétipos.' It then enumerates each action with its specific purpose, so an agent knows this tool is for MBTI quiz/profile/archetype art operations. It does not explicitly contrast with siblings like sapiens_profile or sapiens_sintetico, so it stops short of full sibling differentiation.

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?

Primary vs secondary actions and a suggested workflow are explicit: get_quiz first, collect 48 answers, submit_quiz, then generate 'depois do quiz'; it also notes generate costs 450 Sinapses and list_codes is static. This is clear contextual guidance. No explicit 'use X instead of Y' alternatives are given, so score 4.

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 annotations are minimal, so the description carries the burden—and it does so thoroughly. It discloses idempotency limits, regeneration costs (~900 Sinapses), billing/refund behavior, admin restrictions, and the timeout rule: 'podem cobrar mesmo voltando Timeout; cheque get_carousel/dashboard antes de repetir'. No statement 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 content is dense and almost always relevant, but it is delivered as one long unbroken paragraph with semicolon-separated action lists and mixed-language abbreviations. Key workflows and warnings are buried rather than scannable, making the description harder for an agent to parse efficiently despite its substance.

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 26-action, 42-parameter tool with no output schema, the description covers most operational hazards: return hints, editor URLs, costs, idempotency, ordering rules, and workflow alternatives. It is not exhaustive—some actions lack explicit return descriptions and some parameter combinations are left to inference—but the critical decision-making context is present.

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 only 57% schema coverage, the description compensates heavily by mapping actions to parameters: sourceId/productionId/carouselId origins, withHelen's layout effect, force/makeVisual/generateMissing behaviors, specOverride whitelist validation, and skipFinalize semantics. It also directs the agent to sapiens_meta action=formats for free-form payload schemas.

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

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

The description opens with a specific resource and operation class: 'CRUD do content pipeline Sapiens (sources/productions/publishables)'. It then enumerates 26 sub-actions with one-line explanations, making the tool's scope unambiguous and distinguishing it from the other sapiens_* 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?

The description gives explicit routing guidance: 'prefira ESTE a create_production+payload cru pro carrossel' and 'Pra mega_grafico, SEMPRE prefira run_mega_grafico_full em vez de sequenciar manualmente'. It also names two complete workflows, clarifies admin-only actions, and instructs when to ask the user about withHelen.

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 indicate readOnlyHint=false and openWorldHint=true; the description adds that write actions modify the current session account, that favorite_tool toggles a star, and that invalid/taken update_username requests return {success:false,error}. It does not state persistence/reversibility of follow or favorite mutations, but the core side effects are disclosed.

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

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

The description is dense but earns its length: a 15-action aggregate needs clauses for read/write grouping, routing, and ID provenance. It is front-loaded with the headline purpose before the sub-action inventory, though a bit more line structuring would improve scannability.

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 covers the return shape for the main read actions (badges full list, golden_tools full list, notifications plus unread count) and the error shape for invalid username changes. It relies on session identity for the current user but never explicitly says that get/badges/golden_tools read the session user's profile, a minor gap for a profile tool.

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

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

Schema description coverage is 92%, and the property descriptions already explain each 'action=...' mapping and where IDs come from. The main description repeats that mapping effectively but does not add substantial meaning beyond the schema, so it stays at the baseline for high-coverage schemas.

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

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

The opening line defines the tool as the unified user-profile aggregate and enumerates its contents (identidade + nível/XP + saldo, badges, golden tools), then lists each sub-action with a verb and target. It explicitly distinguishes itself from sibling tools by naming the areas that are NOT duplicated here (sapiens_gallery, sapiens_repertorio, etc.).

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 states when to use this tool and when to go elsewhere: large profile parts are said to have their own dedicated tools, and specific routes are given for discovering IDs (sapiens_community participants/search_users, sapiens_repertorio search_tools). This makes the decision boundary explicit 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?

Beyond the sparse annotations, the description discloses session-token authentication, default draft status, admin review location, and that publishNow=true publishes directly. For a write tool with readOnlyHint=false, this is meaningful behavioral context. It does not describe failure modes or response behavior, but it adds several non-obvious workflow facts.

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

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

The description is a single dense paragraph with no filler or repeated promotional language. It front-loads the three actions and their conditions before the default-status note. The run-on structure makes it slightly harder to scan, but every clause earns its 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?

For a tool with 18 parameters, nested conditional objects, no output schema, and many siblings, the description covers the central branching logic and defaults well. However, it does not describe the expected response/return shape or error behavior, which matters more because no output schema exists, and several secondary parameters are left entirely to the schema.

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

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

With 61% schema coverage, the description adds a useful action-to-object mapping and names the key fields inside quote, popReference, and educativeReference. It also explains the publishNow default. One caveat: saying publish_quote requires a 'complete' quote object (text/author/sourceWork/license/referenceImage/flowImage) is stronger than the schema's required ['text','author'], which could mislead an agent about validation strictness.

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 action ('Publica curado da Coluna Sapiens/Repertório/Educativo') and enumerates three concrete publishing modes with their target columns. It is internally discriminating and explains what the tool creates, but it never explicitly contrasts this tool with the large sapiens_* sibling set, so it stops short of full sibling differentiation.

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 gives clear per-action context: when to use publish_quote, publish_pop, or publish_educativo, and which companion object each requires. It also clarifies the draft-by-default workflow and publishNow bypass. However, it does not name alternative sibling tools or provide explicit when-not-to-use guidance outside these internal modes.

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?

Despite readOnlyHint already being provided, the description adds substantial behavioral detail: pagination behavior (page/limit, hasMore), the distinction between own images (history/favorites) and public/third-party items, and the exact ID/URL usage rules for downstream tools. This goes well beyond the annotation's safety signal and meaningfully shapes how an agent should treat results.

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 and packs a lot of necessary information, but it is presented as one long paragraph rather than structured bullets. Still, most sentences earn their place: the purpose is front-loaded, bucket semantics are explained, and downstream usage rules are included without obvious redundancy.

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

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

Given no output schema, the description compensates well by describing normalized item behavior and how to route imageId/url to other tools. It covers all buckets, pagination, mode, source, filtering options, and an alternative tool for public characters, making it sufficiently complete for an agent 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 coverage is 100%, but the description adds value beyond the property descriptions by explaining bucket semantics, default mode behavior ('mine [default, inclui rascunhos]'), pagination defaults, and cross-tool rules such as using imageId only for own images and url for public items. This materially clarifies how to fill parameters correctly.

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 states the tool's function as the Sapiens global reference popup for browsing media banks and selecting items that become image/video references. It uses specific verbs ('navegar os bancos e pegar') and identifies the resource (reference buckets), and it distinguishes itself from at least one sibling by pointing to sapiens_character action=list_public for public characters.

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 provides explicit context for when to use the tool: to browse reference buckets in read-only mode, with sub-action 'browse'. It also names an alternative for public characters ('Personagens públicos também têm porta dedicada em sapiens_character action=list_public'), but it does not broadly contrast against other sibling tools like sapiens_stock_video or sapiens_gallery, so it stops short of full alternative routing.

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

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

Annotations only convey readOnlyHint=false and openWorldHint=true, so the description carries the burden — and it delivers. It discloses that any logged-in user mutates only their own collection, that the server re-resolves providers and canonicalizes title/cover/year, that upsert/dedup is keyed on (userId, source, externalId), and that tool entries count as 'used' simply by being added. 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 long, but the complexity of 10 actions and 16 parameters justifies it. It is organized into readable sections (reads, mutations, one-shot capture, AI tools) and front-loaded with the core purpose. Some prose is dense and run-on, but nearly every sentence carries necessary 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 large multi-action tool with no output schema, this is unusually complete: it covers action semantics, parameter provenance, failure modes, dedup behavior, authentication requirements, and disambiguation rules. Omitted details such as exact return shapes for list/search are secondary because the action flows are fully specified and the schema defines the inputs.

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 schema description coverage at only 56%, the description compensates heavily. It explains the most error-prone parameters: source/externalId must come from a resolve candidate and must never be fabricated, status inference from natural language (assisti/zerei/li=completed, quero=backlog, etc.), and toolId must come from search_tools. It also clarifies provider meanings such as manual=OMDb for film/series and twitch for games.

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 exactly what the tool is: a personal collection (acervo) spanning media types and AI tools, and enumerates all action families. It clearly distinguishes the two sub-domains (media providers vs the aitag tool catalog) and maps actions to resources, making the scope unambiguous even among many 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?

Provides explicit when-to-use protocols for every action family: reads vs mutations, the resolve-then-add_item flow, one-shot capture trigger phrases, and the failure rule that the agent must not add an entry if resolve returns empty or providerKeyMissing. It also gives concrete when-not-to-act guidance and says to ask only when candidates are ambiguous.

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?

With only readOnlyHint=false and openWorldHint=true in the annotations, the description carries the full burden and does so thoroughly. It discloses that render is asynchronous, what the immediate return shape is ({imageId, status:'rendering', url:null}), that the resulting VEO URL expires quickly, that the operation is admin-only, and that imageId must reference an existing generatedImages row with cost defined. No annotation contradiction.

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?

Every sentence earns its place: purpose first, then argument map, then async behavior, then prerequisites and fallback creation path. Though dense, there is no fluff or repetition, and the most decision-critical details (async, polling, expiration) are prominently marked.

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 async tool with no output schema, the description is remarkably complete. It provides the return shape, the polling workflow until completed/error, the URL expiration warning, the admin-only restriction, prerequisites, and how to satisfy them through sibling tools. An agent has everything needed to invoke and monitor the operation 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 only 40%, but the description compensates comprehensively. It explains imageId as a pre-existing persona found via sapiens_gallery, lists styleId options inline, summarizes the brief structure as product+hook+shots+vibe, and clarifies that references are optional base64 start/end frames defaulting to the persona as start frame.

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 verb and resource: 'render vertical 9:16 via VEO com brief estruturado (admin-only)'. It also names the sub-action 'render' and enumerates the exact inputs, making it clearly distinct from siblings like sapiens_video (status polling) and sapiens_image (image 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?

The description gives explicit workflow guidance: use sapiens_gallery to discover imageId, call sapiens_video action=status to poll, and use sapiens_image action=request_generation to create a prerequisite row when it does not exist. This tells the agent not only when to use this tool but which sibling handles the adjacent steps.

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 discloses side effects, costs, and side conditions far beyond the annotations: send is send-only with daily limits and idempotence via transferId, reflexo_generate charges 450 and refunds on failure, sonda charges with estorno and writes nothing, remember writes a binding directive, and companion changes voice mode. It also clarifies that identity always comes from the token and that consent/custom creation acts remain web-only, 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 long, but the scope justifies it: 18 sub-actions, costs, limits, and prerequisites. It is organized into labeled sections (REFLEXO DE SI, CONVITE, LIBERAÇÃO ADMIN, SONDA, PRÓXIMAS JOGADAS, MODO COMPANHIA) and front-loads the core scope. It loses a point for playful ALL-CAPS phrasing and minor duplication, such as repeating the sidebar-button state in companion.

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 minimal annotations and no output schema, the description carries a heavy burden and meets it: it specifies return values for key actions (status yields name/foto/Cunho/kind + partnerUserId, bonds yields active+pending, sonda yields hooks), pricing, refunds, idempotency, eligibility gates, and web-only consent boundaries. Only minor response-shape details for admin actions are left unspecified, but the workflow sources are clear.

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?

Even with 94% schema coverage, the description adds workflow-level meaning: toUserId should be sourced from status/bonds, hook comes from the sonda output, amount must be a multiple of 100 with min/max limits, and reuse of the same transferId guarantees no duplicate send. It maps each parameter to the actions that use it, turning a static schema into an actionable decision tree.

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 by naming the exact domain — the human↔Sintético bond ('vínculo humano↔Sintético... via MCP') — and bounds it to the logged-in user's own pair. It then enumerates 18 sub-actions with concrete verbs and resources, making it unmistakable what the tool does and clearly distinct from sibling tools like sapiens_persona, sapiens_character, or sapiens_profile.

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 gives strong internal routing: send_context must precede send, invite requires no active bond and has rate-limit/cooldown, and admin actions flow through Helen. It also states explicit exclusions — accepting bond requests and consecrating the Reflexo remain web-only — so the agent knows when not to use this tool. It does not explicitly contrast against sibling tool names, but the domain boundary and sub-action routing are 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?

Annotations only provide readOnlyHint=false and openWorldHint=true, so the description carries the burden of behavioral disclosure. It adds important details: read sub-actions are public and auth-free, generate requires login and costs Sinapses, generation is asynchronous and should be polled via generation-status, failures are reimbursed, and list returns {count, items}. 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 dense and front-loaded with the core purpose, and every clause carries useful information. However, it is a single long paragraph with many intertwined concerns (actions, auth, pricing, async flow, alternatives), which could be more scannable. It is appropriately sized given the tool's complexity, but structure could be improved.

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 tool has 14 parameters, 5 actions, and no output schema, the description is remarkably complete: it covers auth requirements, cost implications, async behavior, polling until ready/failed, list result shape, filtering options, available moods, and routing to the correct sibling. Nothing critical appears missing for an agent to select and 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?

The input schema already covers all 14 parameters with descriptions, so the bar is high. The description adds operation-level meaning beyond the schema, such as explaining that kind='sfx' covers whoosh/clique/impacto/ambiência/foley, clarifying that generated effects are short (1-15s), and describing provider cost differences. Some schema descriptions are duplicated, but the extra context is valuable.

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 (stockAudio audio bank) and the specific actions available (categories, list, get, generate, generation-status), and contrasts it with sapiens_musicator for new music. This goes beyond restating the tool name and differentiates it from 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?

It explicitly tells the agent when to use the tool ('Use pra puxar trilha/efeito pronto... pega a url e usa direto no ffmpeg'), when to fall back to generate ('Não achou o efeito? generate...'), and when to use the sibling tool ('música/trilha nova é no sapiens_musicator'). This is strong when-versus-alternative 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?

Annotations already declare readOnlyHint and openWorldHint, and the description adds meaningful behavior beyond that: 'Leitura pública, sem auth', downloadable/free/internal status, and the exact return shape for list ({count, items} with fields). 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?

Dense but well structured: concept first, then auth, sub-actions, and usage guidance. Every clause carries operational value and there is no filler.

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

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

The tool has 3 actions, 9 parameters, and no output schema, yet the description covers all actions, the list return shape, filters, and concrete use cases. An agent has enough information to invoke it correctly without opening the schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds actionable semantics for key parameters: orientation maps to 9:16/16:9/1:1 and loopOnly maps to clean looping backgrounds for pages. Less central filters like mood, categoryId, and durationMax are left mostly to the schema, so a 4 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?

Description opens by naming the resource ('Banco de clipe/B-roll stock') and the operation ('catálogo de vídeo curto pronto no CDN, baixável'), and enumerates the three sub-actions. It differentiates from sibling sapiens_video by positioning this as the ready-made B-roll source rather than a generator.

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

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

Explicitly states when to use: 'Use pra puxar B-roll pronto em vez de gerar via sapiens_video' and lists concrete integration contexts (page background, ffmpeg B-roll, opening/closing frames). Also gives selection criteria such as orientation and loopOnly that help the agent choose the right clips.

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, so the description correctly communicates that this is not a pure read tool: emancipar 'INICIA o Nível 3' and pulls a blueprint to build on the member's own infrastructure. It stops short of detailing side effects such as whether resources are deployed or state is mutated, but it does disclose the open-world, multi-action nature.

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 text is dense and front-loads the overall catalog purpose, but it is a single long unbroken paragraph and repeats much of the action semantics that already exist in the input schema. The usage triggers and studio list earn their place, but the structure could be tighter.

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-parameter, six-action tool with no output schema, the description maps each action to its return content (mine returns level/brand/operator/tools; list returns URL+status+tags+mcpReady; emancipar returns identity+module index+foundation guide) and lists covered studios/modules. It is largely complete for invocation, with only minor gaps around error/edge-case guidance.

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 slug/action/module/studio/publishableId. The description adds action-level context and example slugs, but it largely restates what the enum and parameter descriptions already say; it stays at 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 opens with 'Catálogo dos estúdios/experimentos Sapiens + o SEU studio + a Emancipação' and enumerates concrete sub-actions (mine/list/get/publishable_url/emancipar/module), so a model can tell it is the studio-catalog and emancipation tool. It is not a tautology and its domain is distinct from the sapiens_* siblings, though the opening phrase is a noun phrase rather than a single crisp verb.

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 gives trigger phrases: 'Use quando user pergunta "que estúdios existem", "qual o meu studio", ou "quero montar meu site/minha casa própria"'. This is a clear when-to-use signal, but it does not contrast with sibling tools or state when not to use this tool.

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?

The description goes well beyond the minimal annotations by disclosing a critical behavioral trait: claim_mission sends proof to the owner's review and never auto-credits Sinapses ('nunca auto-credita por aqui'). It also states identity is always derived from sessionToken, which is important operational context not present in the schema or 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 dense but efficient, with each sentence adding relevant information about sub-actions, parameters, flows, or side effects. It is front-loaded with the overall purpose and then moves from simpler actions to the more complex claim_mission, though the one-block structure could be easier to parse with explicit formatting.

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 there is no output schema, the description compensates well by summarizing what each sub-action returns: title/module/lesson counts for list, module/lesson detail for get, challenge statuses and rewards for list_challenges. It also covers required identity context and the end-to-end flow, making the tool adequately self-contained for correct invocation.

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?

While the schema already documents most parameters, the description adds meaningful context: sub-action semantics, parameter provenance ('o slug vem do list', 'missionId ... vem do list_challenges'), and the acceptable forms of proofText ('link, @handle ou descrição'). This is valuable enrichment beyond the schema's descriptions.

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 managing Sapiens Trilhas and Desafios and enumerates four concrete sub-actions (list, get, list_challenges, claim_mission) with their purposes. It is more specific than the tool name and the action enum, but it does not explicitly contrast this tool with 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?

The description provides explicit flow guidance: 'list → get; list_challenges → claim_mission', and explains that slug comes from list and missionId comes from list_challenges. It does not discuss when to prefer this tool over sibling tools, but the sequencing and prerequisites are clearly 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?

It discloses cost/debiting ('cobra as Sinapses da sua conta'), async behavior ('create é ASSÍNCRONA... volta NA HORA'), idempotency, provider-failure refunds, and variant semantics for sonorize. These behavioral details go far beyond the minimal annotations (readOnlyHint: false, 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 one dense, unstructured block of text with heavy parentheticals, all-caps emphasis, and no sectioning or grouping. The volume is partly justified by 28 parameters and 15 sub-actions, but the lack of organization makes it significantly harder to scan and parse than necessary.

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

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

With no output schema and minimal annotations, the description carries the full burden — and it largely delivers. It covers return shapes like {success, url, imageId, cost}, the rendering status lifecycle, per-model support, admin film workflows, and pricing/refund behavior, making it functionally complete for all sub-actions.

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?

Although schema coverage is already 96%, the description adds substantial meaning: local file limits for startImagePath/endImagePath, mutex rules, references roles with size and duration caps, editOfImageId's 'Nano Banana de vídeo' behavior, and per-model parameter applicability. This is much more than a restatement of 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 'Sapiens Video — gera vídeo' states a concrete verb and resource, and the long sub-action list defines the tool's scope well. However, it never explicitly contrasts with sibling video-adjacent tools like sapiens_shorts or sapiens_stock_video, so it is clear but not a strong differentiator.

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 gives explicit routing guidance throughout: 'Sub-action create (recomendada)' vs 'generate (legado)', 'só no MCP instalado/stdio, não no remoto' with 'No remoto use id/url', and the showcase flow 'demos pra achar o slug, depois showcase'. It also tells the agent not to call create again while a video is rendering, which is a clear when-not instruction.

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 readOnlyHint=false and openWorldHint=true, but the description discloses substantial behavioral traits: the 400 Sinapses cost with refund on failure, synchronous execution subject to timeout, lack of idempotency (blind retry duplicates drafts and re-charges), default courtesy cover behavior, and identity derived from sessionToken. This far exceeds what annotations reveal and directly informs safe invocation.

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 densely packed, and every sentence contributes a distinct operational fact, from the cost and timeout behavior to cover handling and sibling routing. The structure leads with the critical distinction from the editorial blog, then organized sub-actions, then the crucial timeout/idempotency warning—front-loaded and purposeful.

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 18 parameters, 5 actions, no output schema, and complex side effects, the description is notably complete: it covers action-specific behaviors, pricing, failure refunds, timeout implications, idempotency constraints, cover selection logic, and the alternative tool. Nothing essential for an agent 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?

Even with 78% schema coverage, the description clarifies intricate parameter interactions that the schema alone does not convey: how coverImageId/coverImageUrl substitute the courtesy cover, which sourceKind requires which ID parameter, that publish=false returns to draft, and how repertorioItemIds feeds the prompt. This is exactly the cross-parameter meaning an agent needs.

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 by defining the exact scope: self-serve articles of the user himself, appearing at /u/<username>, and explicitly contrasts it with the editorial blog. It then enumerates all five sub-actions (generate, list, get, update, publish), each with a clear verb and resource, making the tool's purpose unmistakable even among many 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?

The description provides explicit when-to-use guidance: it states this is for personal profile articles and not for the curated editorial blog, directing the agent to sapiens_article instead. It also gives conditional usage for covers (use coverImageId/coverImageUrl when you already have an image) and warns against blind retries, telling the agent to check list first.

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