Server Quality Checklist

Tool Scores

• discard_proposalA
  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 full burden of behavioral disclosure. It states that the tool is destructive ('Delete'), scopes behavior to local file removal only, and explicitly excludes external action (LinkedIn). This covers the key behavioral aspects for a simple deletion tool, though it doesn't mention reversibility or side effects.

  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 sentence that front-loads the core action ('Delete a saved proposal'), then adds relevant conditions and scope. There is no wasted wording; every part adds value, making it highly concise and well-structured.

  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 one-parameter delete tool with an output schema present, the description is sufficiently complete. It covers purpose, conditions, and scope. It doesn't detail error handling or edge cases, but those are not essential for basic usage. The scope and behavior are well communicated.

  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% for the single parameter 'proposal_id', but the description implies the parameter is the identifier of the proposal to delete. It doesn't add explicit details about the parameter, but the intuitive meaning is clear from the context. Since there's only one parameter, the description's implication partially compensates for the lack of schema documentation.

  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 operation ('Delete a saved proposal') and specifies the resource and conditions ('that the human rejected or that is no longer wanted'). It explicitly distinguishes from siblings by noting 'Local file removal only — it never touches LinkedIn,' preventing confusion with apply_proposal or other LinkedIn-related 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 context for when to use the tool (when a proposal is rejected or unwanted) and clarifies what it does not do (never touches LinkedIn). It implicitly differentiates from apply_proposal (which would send to LinkedIn) and propose_edit (which edits). It could be stronger by naming alternatives, but the context is sufficient.

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

• get_profileA
  4.5/5.0
  Behavior4/5

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

  Annotations are absent, so the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only — it cannot change anything,' which is the key behavioral trait an agent needs. It also mentions the HTTP method (GET), adding useful implementation context, though it does not discuss authentication or rate limits.

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

  Conciseness5/5

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

  Two sentences, no wasted words. The primary action and read-only guarantee are front-loaded, and the usage guidance is appended in a single clause. Every piece of information earns its place.

  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 no parameters and an output schema present, the description is complete: it names the resource, declares side-effect safety, and explains its role in the edit workflow. No missing information prevents an agent from calling it 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 tool has zero parameters and the schema description coverage is 100% (vacuously). Per the rubric, a baseline of 4 applies to 0-parameter tools; the description does not need to add parameter details and doesn't.

  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 states a specific verb ('Fetch'), a specific resource ('the owner's LinkedIn profile'), and even includes the API endpoint (GET /v2/me). It also clarifies its role relative to a sibling ('before calling propose_edit'), effectively distinguishing it from the editing tool.

  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?

  It clearly states when to use this tool — 'get the person id and current values before calling propose_edit' — providing a concrete use case and sequence. It does not explicitly mention when not to use it or name alternative access tools like auth_status, but its position in the edit workflow is implied.

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

• propose_editA
  4.5/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 behavioral disclosure burden. It clearly states the tool does not write, builds a request, saves a proposal, and returns a diff. It also discloses localization handling for text fields. It does not mention idempotency or error cases, but the non-destructive nature is well communicated.

  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 fairly long but every sentence adds value. It front-loads the core behavioral guarantee, then explains the parameter formats, and ends with locale localization details. There is no redundant fluff; it is compressed for the amount of information conveyed.

  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?

  An output schema exists, so return values need not be described in detail. The description covers the tool's purpose, parameters, workflow, and localization behavior, which is sufficient for an agent to call it correctly. Missing edge cases (e.g., invalid entity_id) are likely handled by the tool's error responses and the output schema.

  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 description coverage is 0%, so the description must compensate. It provides detailed structure for the 'changes' parameter, distinguishing between simple text for headline/summary and action-based objects for position/skill/education. It also explains the locale wrapping behavior, adding significant semantic value beyond the bare schema. The other params (person_id, locale) are self-explanatory via defaults and names.

  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 states a clear verb ('draft'), a specific resource ('profile change'), and explicitly distinguishes its behavior from the sibling apply_proposal by stating it 'NEVER writes to LinkedIn' and returns a diff for human review. This unambiguously differentiates it from the other proposal-related siblings.

  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?

  It explicitly instructs the agent to show the diff to the human, wait for approval, and only then call apply_proposal with the returned proposal_id. This gives both when-to-use and when-not-to-use guidance, clearly routing the agent to the correct sibling after this tool.

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

• auth_startA
  4.6/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 behavioral burden — and it delivers. It discloses side effects (consent page, redirect listener, code exchange, token storage in owner-only 0600 config), explicit non-effects (does not modify profile), and security posture (returns only non-secret status, never the token). This is rich, safety-relevant behavioral disclosure.

  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 dense yet efficient; it front-loads the core purpose and then packs flow details, security caveats, and the alternate mode into a tight sequence of sentences. No word is wasted, and every clause earns its place.

  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?

  An output schema exists, so return-value structure is already covered. The description handles the flow, the url_only alternate mode, and the critical security behavior (never returning the token). The only notable gap is the unexplained timeout_seconds parameter, which leaves a small but real hole in completeness.

  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 description coverage is 0%, so the description must compensate. It fully explains url_only ('just print the authorization URL without starting the listener'), adding real meaning beyond the schema's default. However, timeout_seconds is left entirely unexplained in both schema and description — a genuine gap given no coverage exists anywhere.

  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 states a specific verb and resource ('Run the LinkedIn OAuth sign-in') with a precise breakdown of the flow: opens consent page, catches redirect, exchanges code, stores token. The sentence 'Does NOT modify the profile' distinguishes it from profile-editing siblings like propose_edit and apply_proposal. This clearly differentiates it from auth_status, which merely reports status.

  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 context for the primary OAuth startup flow and explicitly explains the url_only=true alternate mode ('just print the authorization URL without starting the listener'). However, it does not explicitly route the agent to auth_status for checking existing auth state, though the 'Does NOT modify the profile' statement offers a weak exclusion against profile tools.

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

• list_proposalsA
  4.6/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. It explicitly discloses that the tool is local, read-only, makes no network call, and doesn't alter the profile. This transparently conveys the non-destructive nature. It doesn't mention error behavior or sorting, but for a read-only list tool this coverage is adequate.

  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 with no filler. The primary purpose is front-loaded, followed by the read-only note and the parameter explanation. Every sentence earns its place and the structure is easy to parse.

  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 simple read-only tool with one optional parameter and an output schema present, the description is complete. It explains purpose, behavior, and the parameter. No additional information is needed for an agent to call it correctly.

  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?

  Despite schema coverage of 0%, the description directly explains the only parameter: 'Set include_applied=true to also show proposals that have already been sent.' This adds clear meaning beyond the schema's bare 'Include Applied' title, enabling correct usage without needing to inspect 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 specific action (list) and resource (saved edit proposals) along with what's included (their diffs). It distinguishes itself from sibling tools like propose_edit, apply_proposal, and discard_proposal by being the read-only listing operation, leaving no ambiguity about its role.

  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 context for when to use it: 'Local read only — no network call and no profile change' indicates it's for inspecting proposals without side effects. However, it doesn't explicitly state when not to use it or name alternatives, so it lacks direct exclusions, but the context is sufficient for an agent to infer its usage.

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

• auth_statusA
  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 of behavioral disclosure. It explicitly states that it reads local config only, makes no network call, causes no profile change, and never returns the token value. This is a thorough disclosure of its operational limits and side effects, leaving no ambiguity about its safety and read-only nature.

  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 sentence, front-loaded with the primary purpose ('Report whether...') followed by critical behavioral constraints. Every clause adds value, with no waste or redundancy. The structure is efficient and immediately actionable.

  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 has no parameters and an output schema exists (so return values are handled externally), the description is complete for an agent to call it correctly. It covers what, how, and safety considerations. The only omission is usage timing relative to siblings, but that is adequately covered by usage guidance and does not detract from completeness.

  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 of 4 applies. The description does not need to explain parameters because there are none. The schema is trivially complete at 100% coverage, and the description adds no parameter-related information, which is appropriate given the absence of parameters.

  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 starts with a specific verb 'Report' and specifies the resource: 'whether a LinkedIn access token is stored and when it expires.' It clearly distinguishes this tool from siblings like auth_start (which would initiate authentication) and get_profile (which retrieves profile data). The scope is well-defined.

  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 states 'Reads local config only: no network call, no profile change' which implies it is a safe, read-only check, but it does not explicitly name alternatives or exclusions. The context is clear enough that an agent would infer this is for checking auth status before proceeding, but it could be more explicit about when to use it versus auth_start.

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

• apply_proposalA
  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 of behavioral disclosure. It reveals the mutation side effect (writes to LinkedIn), the code-enforced approval format that must match exactly, the expectation of invalid-scope/permission errors until LinkedIn grants API access, and the instruction to report errors plainly without workarounds. This is exceptional transparency for a write operation.

  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 three sentences, each dense with purpose. The critical differentiator is front-loaded, followed by the approval gating and error-handling context. There is zero filler; every sentence earns its place.

  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?

  Despite no annotations, the description covers the full operational context: the single-write constraint, the mandatory human approval with exact argument format, the expected error condition and correct response (report and stop), and the relationship to propose_edit. With an output schema available to describe return values, nothing essential is missing for an agent to call this 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?

  Given schema description coverage is 0%, the description must fully explain parameter meaning. It does for 'approval' by specifying the exact string format ('approve <proposal_id>') and its role in the approval flow. For 'proposal_id', it links it to 'the single prepared request stored in one proposal', conveying its purpose, although it doesn't explicitly state where to obtain it (though imply it via propose_edit). This is sufficient value 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 opens with 'THE ONLY TOOL THAT WRITES TO LINKEDIN', which immediately identifies the unique action (write) and resource (LinkedIn) while distinguishing it from every sibling. It then specifies it sends the single prepared request stored in one proposal, making the verb and object unambiguous.

  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?

  It explicitly states the precondition (human approval of the diff) and the prohibition against calling it on your own initiative or immediately after propose_edit without approval. This clearly delineates when to use it vs. alternatives like propose_edit, which creates the proposal that this tool then applies.

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