Server Quality Checklist

Tool Scores

• capture_linkedin_posts_and_commentersA
  4.4/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, and the description aligns with all of them. It goes well beyond the annotations by disclosing concrete behavioral traits: no credentials needed, approximately ten comments are shown to logged-out visitors (3.7% coverage), 30% of comment rows lack timestamps, reactors are unavailable without login, and every row carries degraded and degradation_reason. This is exemplary transparency.

  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 average, but every sentence carries distinct value: purpose, data model, key fields, limitations, degraded flags, and prerequisites. It is front-loaded with the core function and then layers caveats logically. It is dense but not wasteful; a perfect 5 would require slightly tighter phrasing without losing needed caveats.

  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?

  This tool has no output schema and seven optional parameters, but the description compensates fully: it explains the three row types, stable post_id semantics, commenter and reactor limitations, degraded flag usage, and the requirement for APIFY_TOKEN and credits. There is no missing context an agent would need to call the tool correctly and interpret results.

  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 100% and each parameter in the input schema has a detailed description (e.g., posted_since skips before charge, max_engagers_per_post caps at ten, collect_reactors returns no rows). The tool description itself does not add significant parameter-specific semantics beyond the schema; it focuses on output structure and limitations. Per the rubric, the high schema coverage supports a baseline of 3.

  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 precise statement of what the tool does: it points at LinkedIn person or company pages and returns posts, reaction/comment counts, and public commenters as flat rows. It also immediately distinguishes the data model with row_type, making the purpose unmistakable. No sibling tools exist, so differentiation is not applicable, but the purpose is specific and actionable.

  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?

  There are no sibling tools to contrast against, but the description gives strong operational guidance: filter on row_type before loading, use post_id as a primary key, check degraded before trusting absences, and read limits before relying on commenters. It does not explicitly state 'use this when X instead of Y', but the context it provides is sufficient for an agent to decide when this tool is appropriate.

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