sapiens_article

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.