Server Quality Checklist

Tool Scores

• set_published_statusC
  2.7/5.0
  Behavior2/5

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

  No annotations are present, so the description carries the full burden of behavioral disclosure. It only states the action ('change status') without revealing side effects, reversibility, permission requirements, or consequences of setting to 'error' or 'completed'. This is insufficient for a mutation tool.

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

  Conciseness4/5

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

  The description is a single, efficient sentence that gets to the point without wasted words. It is well-structured and front-loaded with the core action, though it is terse and omits important usage and parameter context.

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

  Completeness2/5

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

  For a tool with no annotations, no output schema, and 0% parameter description coverage, the description is too minimal. It does not explain the impact of status changes, expected return values, or any edge cases. The lack of behavioral and parameter detail makes it inadequate for confident invocation.

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

  Parameters2/5

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

  The input schema has 0% description coverage, and the description does not add meaning beyond what the schema already provides. The status enum is repeated in the description, but the id parameter is unexplained, and no values or usage details are given. With only 2 parameters, the description fails to compensate for the schema gap.

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

  Purpose4/5

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

  The description clearly states the action ('Change le status') and the resource ('PublishedLeadMagnet'), and lists the possible statuses. While it doesn't explicitly distinguish from sibling tools, the unique status-setting function is evident.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus siblings like publish_lead_magnet or toggle_published_dm. There is no mention of prerequisites, exclusions, or alternatives, leaving the agent to infer usage from the name alone.

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

• register_publishedC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description must disclose the tool's behavior. It explains that it stores a snapshot and the post URN for tracking, but it does not mention side effects, such as whether it creates a record, whether auto_dm_enabled triggers a DM automation, or any permissions needed. For a write operation, this is insufficient.

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

  Conciseness4/5

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

  The description is a single, focused sentence that front-loads the action and includes no redundant detail. It efficiently communicates the core purpose. It could benefit from a brief mention of other stored fields, but as is, it is appropriately concise.

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

  Completeness2/5

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

  Given the tool's complexity (9 parameters, nested objects) and lack of output schema, the description is too sparse to be complete. It does not explain what the tool returns, how auto_dm_enabled behavior is handled, or the role of required cta_keyword. The description covers the registration concept but leaves critical usage context uncovered.

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

  Parameters2/5

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

  With only 22% schema coverage, the description must explain the many undocumented parameters. It adds meaning for post_urn ('URN du post LinkedIn') and input_payload ('snapshot du LeadMagnetInput'), but leaves cta_keyword, archetype, post_text, visual_spec, resource_url, auto_dm_enabled, and resource_message unexplained. This is a significant gap for a 9-parameter tool.

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

  Purpose4/5

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

  The description clearly states the tool's action ('Enregistre' = registers) and resource ('lead magnet publié sur LinkedIn'), and explains the purpose (snapshot for engagement tracking). This distinguishes it from siblings like publish_lead_magnet and list_published. It could be more explicit about being an after-publishing step, but the 'publié' condition makes the intent clear.

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

  Usage Guidelines3/5

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

  The description implies this tool is for lead magnets that are already published on LinkedIn, which gives contextual guidance. However, it does not explicitly state when not to use it or mention alternatives like publish_lead_magnet or update_post. The usage is only implied, not clearly framed with exclusions.

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

• mark_engagement_sentB
  3.1/5.0
  Behavior2/5

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

  No annotations are provided, so the description must carry the full burden. It fails to mention side effects such as whether the operation is reversible, overwrites previous state, or requires certain permissions. The manual LinkedIn context is useful but insufficient for full behavioral transparency.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that conveys the core action without any fluff. It is succinct and well-structured, making it easy to scan.

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

  Completeness2/5

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

  Given the tool's simplicity but lack of annotations and output schema, the description is too sparse. It omits parameter semantics, side effects, and prerequisites, leaving gaps that an agent would need to infer. For a 2-parameter tool, more context is expected.

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

  Parameters1/5

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

  Schema description coverage is 0% and the description does not explain the parameters. While 'CommentEngagement' hints that 'id' references an engagement, the 'sent' parameter is entirely unmentioned, and no guidance is given on expected values or behavior. The description adds no value beyond the raw schema.

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

  Purpose5/5

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

  The description clearly states the verb 'marks' and the specific resource 'CommentEngagement', indicating a state change to 'DM sent'. It also adds the manner 'manually via LinkedIn', which distinguishes it from sibling tools related to published content, making its purpose unambiguous.

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

  Usage Guidelines3/5

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

  The description implies the use case for manually sent DMs via LinkedIn, giving some context. However, it does not explicitly state when not to use it or mention any alternative tools, so the guidance is implied rather than explicit.

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

• list_corpusB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden. However, it contains a contradictory count (45 entries vs 30+ posts + 45 images), which is confusing. It also does not explicitly state that it is a read-only operation or describe output format/pagination.

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

  Conciseness4/5

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

  The description is a single sentence, front-loaded with the core action. However, the parenthetical breakdown of entries is cluttered and contains confusing arithmetic, reducing overall clarity despite its brevity.

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

  Completeness2/5

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

  With no output schema, the description should explain what is returned but does not, and the count inconsistency adds ambiguity. It provides context about the corpus and filter/sort options, but these are not enough to fully understand the tool's behavior for a 3-parameter list operation.

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

  Parameters2/5

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

  Schema coverage is only 33%, and the description adds minimal value beyond the schema. 'Filtrable par archetype' repeats the archetype parameter description, and 'tri par engagement' only mentions one of the two order_by enum values without explaining the 'archetype' sort option. The 'limit' parameter is not explained at all.

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

  Purpose5/5

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

  The description clearly states the tool lists lead magnets from the reference corpus, using a specific verb (liste) and resource. It distinguishes itself from siblings like list_published by specifying 'corpus de référence'.

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

  Usage Guidelines3/5

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

  The description implies when to use it (listing corpus entries) and mentions filter/sort capabilities, but it does not explicitly state when not to use alternatives or provide exclusions. It relies on the name and context.

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

• toggle_published_dmB
  3.3/5.0
  Behavior2/5

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

  With no annotations, the description carries full burden of behavioral disclosure. It states the core toggle action but does not mention permissions, reversibility, side effects, or whether it is idempotent. For a mutation tool, this is a gap.

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

  Conciseness5/5

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

  The description is a single, efficient sentence with no wasted words. It is front-loaded and directly communicates the tool's purpose.

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

  Completeness3/5

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

  For a simple 2-parameter toggle tool with no output schema, the description provides the core action but lacks behavioral context (side effects, permissions) and full parameter explanation. It is minimally adequate but has clear gaps.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. It adds meaning by mapping the enabled parameter to auto_dm_enabled, but the id parameter is not explained, and there is no detail on allowed values or semantics beyond the schema's primitive types.

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

  Purpose5/5

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

  The description clearly states the tool toggles the auto_dm_enabled field on a PublishedLeadMagnet, using a specific verb ('Active/désactive') and resource. It distinguishes itself from siblings like set_published_status by targeting a specific boolean field.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool versus alternatives, no exclusions, and no context on prerequisites. The description merely states what it does, leaving the agent to infer usage.

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

• get_published_detailA
  3.7/5.0
  Behavior3/5

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

  No annotations are provided, so the description must disclose behavior. It states the tool returns detail and engagements (comments and DM status), which gives some behavioral context. However, it does not explicitly state that this is a read-only operation, nor does it disclose any side effects, permissions, or error behaviors. The name 'get' implies read-only, but the description itself does not confirm it.

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

  Conciseness5/5

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

  The description is a single, dense sentence that front-loads the key information. No wasted words.

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

  Completeness4/5

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

  Given the tool's simplicity (one parameter, no output schema), the description covers the core purpose and return content. It could be improved by specifying the output shape or clarifying that engagements are included as part of the detail. Overall, it's an adequate but not exhaustive description.

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

  Parameters4/5

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

  The schema only defines 'id' as an integer with no description. The description compensates by indicating that the id corresponds to a PublishedLeadMagnet, giving meaning to the parameter. This is sufficient for a single simple parameter.

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

  Purpose4/5

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

  The description clearly states the tool provides the detail of a PublishedLeadMagnet plus its engagements (comments and DM status). This distinguishes it from list_published which lists items, and from other mutation tools in the sibling set. However, it does not explicitly contrast against any sibling, so it stops short of maximum clarity.

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

  Usage Guidelines3/5

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

  The description implies the tool is for retrieving detailed information for a single published lead magnet, but it does not explicitly state when to use it versus list_published or other tools. There is no mention of alternatives or exclusions, so usage guidance is only implicit.

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

• generate_pairA
  3.8/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses legacy status ('Pipeline v3 legacy') and internal coupling process ('coupled motifs + proof gate'). However, it does not mention side effects, prerequisites, or whether the tool is read-only, which would be important for full transparency.

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

  Conciseness5/5

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

  Two concise sentences, front-loaded with purpose, and every sentence earns its place by including legacy status, output, and alternative guidance.

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

  Completeness3/5

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

  The description conveys core purpose, legacy status, and alternative, and describes the output (2 variants). However, for a 5-parameter tool with no output schema or annotations, it lacks parameter explanations and return format details, leaving the agent under-informed on how to invoke it correctly.

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

  Parameters1/5

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

  Schema description coverage is 0%, but the description adds virtually no parameter information. It mentions 'biais/motifs' but does not map this to any of the 5 parameters (topic, tone, claim, proof_override, user_has_upload).

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

  Purpose5/5

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

  The description clearly states it generates 2 variants (hook + image SPEC) coupled via pair_generator. It distinguishes itself from the sibling generate_lead_magnet by specifying it remains for explicit retrieval via bias/motifs.

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

  Usage Guidelines5/5

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

  Explicitly says 'Utilise plutôt generate_lead_magnet' (prefer generate_lead_magnet) and clarifies that this tool remains for explicit retrieval via bias/motifs, providing clear when-to-use vs. alternative guidance.

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

• list_publishedA
  3.8/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states what is listed and the presence of stats, but does not mention any potential side effects, authentication requirements, pagination, or other behavioral traits. While 'list' implies a read-only operation, this is not explicitly stated.

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

  Conciseness5/5

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

  The description is a single, concise sentence that front-loads the action and resource, and includes the key detail about rolling engagement stats. No unnecessary words are present.

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

  Completeness4/5

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

  For a simple list tool with no parameters and no output schema, the description adequately conveys what the tool does, including the resource type and the included stats. It lacks details about response structure, but the tool's simplicity makes this acceptable.

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

  Parameters4/5

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

  The tool has zero parameters, so the baseline score is 4. The description does not reference parameters, but none exist to explain. The empty schema already covers all parameter-related information.

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

  Purpose5/5

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

  The description clearly states the tool lists the user's published lead magnets and includes rolling engagement stats, using a specific verb and resource. This distinguishes it from sibling tools like list_corpus and get_published_detail.

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

  Usage Guidelines3/5

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

  The description implies usage for listing published lead magnets with engagement stats but provides no explicit guidance on when to use this tool versus alternatives such as list_corpus or get_published_detail. No exclusions or alternative recommendations are given.

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

• prepare_visual_baseA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses the underlying model (Gemini 2.5 Flash Image) and the output format (data URL), which is useful. However, it does not mention side effects, permissions, error handling, or whether the operation is read-only or has any side effects. This is a generation tool, so some behavioral transparency is provided, but gaps remain.

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

  Conciseness5/5

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

  The description is a single, concise sentence that packs in the purpose, method, and output. Every word contributes to understanding, with no redundancy or filler. It is front-loaded with the most important information first, making it highly efficient.

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

  Completeness4/5

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

  Given the tool's low complexity (one parameter, no output schema), the description covers the essential aspects: what it does, the model used, and the return value (data URL). It does not discuss error conditions or prerequisites, but for a simple generation tool with a clear output, this level of completeness is sufficient. The lack of an output schema is compensated by the explicit return description.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. The only parameter, base_prompt, is mentioned in the description as the source for generating the background. This confirms its role but adds little beyond what the parameter name already implies. No examples or additional guidance are provided, so it meets the minimum but does not fully enrich the parameter semantics.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: generating a cinematic background via Gemini 2.5 Flash Image for the dark_thumbnail archetype. It names a specific verb ('génère'), resource ('fond cinematic background'), and input ('base_prompt'). However, it does not explicitly distinguish this from sibling tools like render_visual, which could also generate visuals, so it lacks 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.

  Usage Guidelines4/5

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

  The description provides a clear usage context: it is intended for the dark_thumbnail archetype, which tells the agent when to use this tool. It does not explicitly mention alternatives or when not to use it, but the archetype restriction implies a specific scenario. This is clear context without exclusions, so it earns a 4 rather than a 5.

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

• generate_lead_magnetA
  3.9/5.0
  Behavior4/5

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

  The description discloses valuable behavioral traits beyond the schema: it streams NDJSON events in a specific sequence (validation → post → visual_spec → done) and returns a list of parsed events. With no annotations provided, this information is crucial for the agent to handle the output correctly.

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

  Conciseness5/5

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

  The description is two concise sentences, front-loaded with the primary purpose and followed by the streaming output behavior. Every sentence adds essential information without redundancy.

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

  Completeness3/5

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

  The description provides a solid overview of the tool's purpose and output flow, which is adequate for a basic understanding. However, given the complexity of 14 parameters, nested objects, no output schema, and no annotations, it leaves gaps around required parameters, potential event types, and error conditions, making it only partially complete.

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

  Parameters3/5

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

  The description mentions key input categories (outils, chiffre+source, type de preuve) that map to several parameters, providing some semantic context. However, schema coverage is only 36%, and the description does not compensate for all undocumented parameters, leaving many fields (e.g., audience, workshop_date, auto_dm_enabled) without contextual guidance.

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

  Purpose5/5

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

  The description clearly states the tool generates a complete LinkedIn lead magnet (text post + visual_spec) from structured input, which is a specific action and resource. It distinguishes itself from siblings like render_visual and publish_lead_magnet by focusing on generation of content, not rendering or publishing.

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

  Usage Guidelines3/5

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

  The description implies this tool is for generating lead magnets, but provides no explicit guidance on when to use it versus alternatives like render_visual or publish_lead_magnet. The usage context is inferable but not directly stated.

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

• render_visualA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of disclosure. It states the output is a base64-encoded PNG with mime-type, dimensions, and supported archetypes, which gives clear behavioral insight. It does not mention error handling or side effects, but for a render tool, these are less critical and the key output details are covered.

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

  Conciseness5/5

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

  The description is two sentences with no redundant content. It front-loads the core action and includes essential details (output format, dimensions, archetype count) without unnecessary words.

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

  Completeness4/5

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

  Given the tool's simplicity and the schema covering the parameter, the description adequately covers the main aspects: input, output, format, and constraints. It lacks details about potential errors or prerequisites, but the core functionality is well specified, making it sufficient for selection and basic invocation.

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

  Parameters4/5

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

  The schema already describes the 'spec' parameter as a LeadMagnetVisualSpec discriminated by archetype. The description adds the fact that 8 archetypes are supported, which provides extra semantic value beyond the schema. However, it does not detail how to construct or specify the spec, but the schema covers the type.

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

  Purpose5/5

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

  The description clearly states the tool renders a LeadMagnetVisualSpec into a PNG, specifying dimensions (1080x1080 or adapted ratio) and return format (base64 + mime-type). This is specific and distinguishes it from sibling tools like render_gif.

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

  Usage Guidelines3/5

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

  The description implies usage when a PNG rendering of a visual spec is needed, and mentions supported archetypes, but it does not explicitly differentiate from related tools like render_gif or provide when-not-to-use guidance. The context is sufficient to infer applicability but lacks explicit exclusions.

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

• whoamiA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of disclosure. It clearly states the tool returns user info, implying a read-only operation, but it does not describe what specific information is returned (e.g., user ID, email, permissions) or how errors like invalid MCP keys are handled. It adds some context by mentioning 'via la clé MCP' but could be more explicit about behavior.

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

  Conciseness5/5

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

  The description is a single, short sentence that is front-loaded with the main action and purpose. Every word earns its place, with no fluff or repetition.

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

  Completeness4/5

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

  For a simple, zero-parameter tool with no output schema, the description provides the essential purpose and a use case. It lacks details on the exact return format, but given the trivial complexity, it is reasonably complete. It could mention error behavior or the exact fields returned, but this is not critical for a 'whoami' tool.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema already fully covers this. The description does not need to explain parameters, and it adds no parameter-related semantics. Per the baseline for zero-parameter tools, a score of 4 is appropriate.

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

  Purpose5/5

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

  The description uses the specific verb 'retourne' and identifies the resource as 'les infos du user authentifié', making it clear this tool returns authenticated user info. It also adds the scoping detail 'via la clé MCP' (via MCP key), which distinguishes it from the sibling tools that deal with rendering, publishing, and corpus operations.

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

  Usage Guidelines4/5

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

  The phrase 'utile pour debug auth' explicitly gives a use case: debugging authentication. This provides clear context on when to use this tool. However, it does not mention when not to use it or name alternative tools, but given there are no similar siblings, it is adequate.

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

• paste_commentsA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the responsibility for behavioral disclosure. It reveals that the tool parses, matches calls-to-action, and generates ready-to-copy DMs, while also noting the limitation that automatic sending is impossible. This provides meaningful context beyond what schema or annotations offer.

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

  Conciseness4/5

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

  The description is a single, information-dense sentence. It covers inputs, processing, outputs, and a constraint without excessive verbosity. Minor noise like 'Sprint E.3' Option B' and French-only phrasing prevent a perfect score.

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

  Completeness4/5

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

  For a tool with only 2 simple parameters and no output schema, the description provides sufficient context: it explains the entire workflow (paste → parse → match → generate) and the manual assembly outcome. It doesn't detail the output structure, but that is not critical for basic invocation.

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

  Parameters4/5

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

  Schema coverage is 100% with descriptions for both id and raw_text. The description adds value by specifying input formats (tab, pipe, free-form) and explaining the output purpose (personalized DMs), which the schema does not convey. This raises it above the baseline.

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

  Purpose5/5

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

  The description clearly states the tool's action: importing user-pasted LinkedIn comments, parsing them, matching the CTA, and generating personalized DMs. This specific verb+resource combination distinguishes it from sibling tools focused on rendering, publishing, or listing.

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

  Usage Guidelines4/5

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

  The description defines the use case: when the user pastes LinkedIn comments in formats like tab, pipe, or free-form. It also explains a key constraint (LinkedIn r_member_social is CLOSED, so auto-send is impossible), guiding the agent to use this tool for manual copy-paste workflows. It doesn't explicitly name alternatives, but siblings are clearly different.

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

• find_similar_corpusA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries full responsibility for behavioral transparency. It discloses the scoring algorithm (embedding cosine + engagement bump with log10 likes), which explains how results are ranked. The wording clearly implies a read-only retrieval operation, though it doesn't explicitly state that.

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

  Conciseness5/5

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

  The description is two short sentences. The first front-loads the core purpose ('RAG retrieval'), and the second provides a concise scoring formula. Every word earns its place with no redundancy.

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

  Completeness4/5

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

  For a retrieval tool with no output schema and no annotations, the description adequately covers the main aspects: what it returns, how results are scored, and optional parameters. A minor gap is that it doesn't specify the structure of each returned lead magnet, but that's often understood from context.

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

  Parameters4/5

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

  The schema already covers 75% of parameters with descriptions, but the description adds extra meaning: it clarifies 'k' as top-K, describes 'query' as free text, and states that 'brands' are optional. The scoring formula also explains how 'k' results are selected, going beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool's function: it returns the top-K lead magnets from the corpus most similar to a query. The specific verb 'retourne' and resource 'lead magnets du corpus' distinguish it from sibling tools like list_corpus (listing all) and generate_lead_magnet (creating).

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

  Usage Guidelines4/5

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

  The description provides a clear context for usage: 'RAG retrieval' and 'most similar' imply this is for similarity-based search on the corpus. It doesn't explicitly name alternatives or exclusions, but the intended use case is evident. This qualifies as 'clear context, no exclusions'.

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

• poll_published_nowA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently mentions the legacy status, the forced poll behavior, the empty engagements result, and the underlying cause (r_member_social being CLOSED). It does not discuss side effects, authentication, or rate limits, but for a simple one-parameter tool this covers the critical behavioral outcomes.

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

  Conciseness5/5

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

  The description is a single, dense sentence that contains the purpose, legacy warning, behavioral consequence, and an alternative recommendation. Every word adds value, and the structure is front-loaded with the core action.

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

  Completeness4/5

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

  The tool is simple (one parameter, no output schema, no annotations). The description covers the essential context: what it does, why it's legacy, what result to expect (empty engagements), and the preferred alternative. It lacks a detailed response shape, but the empty-engagements warning largely compensates for the absence of an output schema.

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

  Parameters3/5

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

  The schema has 0% description coverage and only one required integer parameter 'id'. The description mentions 'sur un PublishedLeadMagnet', which implies that 'id' refers to the PublishedLeadMagnet's ID, but it does not explicitly state this mapping. Given the low schema coverage, the description adds some context but could be more explicit about the parameter's semantics.

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

  Purpose5/5

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

  The description clearly states the tool's action: 'Force un poll Community API immédiat sur un PublishedLeadMagnet' (force an immediate Community API poll on a PublishedLeadMagnet). It specifies the verb 'force', the resource 'PublishedLeadMagnet', and the scope 'immédiat'. It also distinguishes itself from siblings by explicitly naming 'paste_comments' as the preferred alternative.

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

  Usage Guidelines5/5

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

  The description gives explicit usage guidance: it labels the tool as 'legacy', states that it 'retournera des engagements vides' (will return empty engagements), explains why ('r_member_social est CLOSED'), and directly recommends 'préférer paste_comments'. This clearly tells the agent when not to use it and which sibling to choose instead.

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

• publish_lead_magnetA
  4.5/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries the full burden. It fully discloses the side effects: the first call does not publish, the second call publishes, and it enforces a mandatory human confirmation. It also explains the resource_url pre-publication check and that the tool returns post_urn for chaining with register_published. This is rich, transparent behavioral detail.

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

  Conciseness5/5

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

  The description is concise and well-structured: it leads with the purpose, then clearly outlines the two mandatory phases, the confirmation requirement, and the resource testing rule. Each sentence provides essential information without redundancy, and the use of ALL-CAPS for key warnings is effective.

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

  Completeness5/5

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

  For a tool with 7 parameters, no output schema, and no annotations, the description covers all critical aspects: the two-phase workflow, the need for explicit user consent, the resource_url check, and the return value (post_urn) plus the recommended follow-up action (register_published). It is complete enough for an agent to use the tool correctly.

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

  Parameters3/5

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

  The input schema has 100% coverage with descriptions for all 7 parameters, so the baseline is 3. The description adds context about the two-phase flow and mentions resource_url testing, but the schema already documents that resource_url is 'vérifiée avant publication'. The description does not add significant parameter-specific meaning beyond what the schema already provides.

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

  Purpose5/5

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

  The description clearly states the tool publishes a lead magnet on LinkedIn ('Publie un lead magnet sur LinkedIn'), using a specific verb and resource. It distinguishes itself from the webapp workflow and from siblings by describing the two-phase publishing process and mentioning chaining with register_published, making its unique role evident.

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

  Usage Guidelines4/5

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

  The description provides strong usage context: it must be called twice (first for preview, second with confirmed=true after explicit user consent), and it explicitly instructs not to confirm on the user's behalf. It also mentions testing resource_url before publishing. However, it does not explicitly state when to use this tool versus alternatives (e.g., generate_lead_magnet, update_post), only implying its role through the publishing workflow.

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

• add_memoryA
  4.6/5.0
  Behavior5/5

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

  With no annotations provided, the description fully carries the behavioral transparency burden. It discloses important traits: mandatory source fields with consequences of missing provenance, scope-based retrieval filtering, and deduplication making replay harmless. This provides substantial insight into how the tool behaves.

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

  Conciseness4/5

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

  The description is a single dense paragraph of three sentences, each carrying essential information about purpose, constraints, and behavior. It is slightly verbose but every sentence earns its place with no filler.

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

  Completeness4/5

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

  Given the tool's complexity (7 parameters, 4 required), the description covers purpose, usage guidelines, parameter semantics, and key behavioral traits without relying on external annotations or an output schema. It lacks only an explicit explanation of return values, which is not expected for a write operation without an output schema.

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

  Parameters5/5

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

  Although schema coverage is 100%, the description significantly enriches parameter understanding. It explains why source and source_date are mandatory, clarifies valid kind values and explicitly excludes learned_rule/anti_pattern, and describes how scope filters retrieval. This goes well beyond the schema's field descriptions.

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

  Purpose5/5

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

  The description clearly states the tool writes a memory entry with a specific verb and resource ('Ecrit une entree dans la memoire de l'utilisateur'), making its purpose unambiguous. It differentiates from sibling tools by framing it as the entry point for the second brain, distinct from visualization, lead generation, and publishing tools.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: it is for knowledge the user has that Publiar hasn't seen ('ce que tu sais et que Publiar n'a pas vu passer'). It also explicitly refuses certain kinds (learned_rule, anti_pattern), indicating when not to use those. However, it does not explicitly name alternative tools for those cases.

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

• render_gifA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and delivers richly. It discloses resolution, loop behavior, memory cost (528 MB peak), a verification date and method, the known cause of prior failures (/v2/assets not supporting GIF), and the one unverified aspect (whether the feed actually plays the animation). This is far beyond typical.

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

  Conciseness4/5

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

  The description is longer than ideal but every sentence adds distinct value—purpose, recipes, verification, failure cause, cost, and alternative guidance. It is front-loaded with the core purpose and tapers off into details. No wasted words, though it could be tightened slightly without losing information.

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

  Completeness4/5

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

  Given the absence of annotations and output schema, the description is remarkably complete: it covers what, when, why, cost, failure modes, and caveats. The only missing piece is an explicit statement of the return value/artifact structure, though it indirectly mentions the artifact name. For a render tool, this is sufficiently complete.

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

  Parameters4/5

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

  The schema provides only a bare 'spec' object with 0% coverage. The description compensates by naming the two recipes and their fields ('tool_pairing': brands[], connector, caption_bottom; 'metric_counter': value, unit, prefix, label, caption_bottom), giving meaning to the otherwise opaque parameter. It could go further by explicitly mapping these to the spec object, but it already adds substantial value.

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

  Purpose5/5

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

  The description opens with a clear statement: 'Rend un lead magnet ANIME en GIF (1080x1080, boucle infinie)' – a specific verb, resource, and format. It also lists the two supported recipes, immediately distinguishing it from render_visual, which is explicitly referenced as the fallback for non-animated needs.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance: 'reste sur render_visual quand l'animation n'apporte rien' clearly states when NOT to use this tool. It also details the two recipes for the spec object, telling the agent how to structure requests for different animation types.

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

• update_postA
  4.9/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and does an excellent job. It discloses the two-phase confirmation flow (preview without changes, then confirmed call), the non-modifiability of the visual, the full replacement of text rather than merging, and the preservation of URN, date, and engagement. These are all behaviors beyond a generic 'update' and are clearly spelled out.

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

  Conciseness5/5

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

  The description is appropriately sized for the tool's complexity, with each sentence serving a purpose. It is front-loaded with the core action, then provides usage context, process, and constraints. Though longer than the average tool description, it is information-dense and well-structured, with no redundant filler.

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

  Completeness5/5

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

  Given the tool's complexity (mutation with two-phase confirmation) and no output schema, the description is remarkably complete. It explains the preview return ('retourne l'avant et l'apres'), the mandatory two-phase flow, the visual limitation, and the full-text replacement requirement. No critical aspect is missing for the 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.

  Parameters4/5

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

  The schema already provides 100% coverage of parameters, so baseline is 3. The description adds valuable semantic context beyond the schema: it explicitly instructs to pass the ENTIRE text ('Passe le texte ENTIER, pas un fragment') and clarifies the replacement behavior, which is not in the schema. It also reinforces the confirmed parameter's role in the two-phase flow, adding meaning beyond the schema description.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb and resource: 'Reecrit le texte d'un post LinkedIn DEJA publie' (rewrites the text of an already published LinkedIn post). It distinguishes from siblings by emphasizing editing over republishing and mentions preservation of URN, date, and engagement, which are unique to this update operation.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use the tool: 'Sert quand le hook est rate ou qu'une affirmation s'avere fausse' (used when the hook is missed or a claim turns out false). It also contrasts with republishing ('editer bat republier') and explains the two-phase process similar to publish_lead_magnet, providing clear guidance and an alternative.

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