Server Quality Checklist

Tool Scores

• app_statusA
  4.3/5.0
  Behavior3/5

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

  The readOnlyHint and openWorldHint annotations already convey that this is a safe, read-only operation. The description adds that it checks installation, running state, and bridge location on the local machine, but it does not describe return format, error behavior, or what 'integration bridge' concretely means. This is acceptable but not especially rich.

  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 communicates the resource, the exact checks being performed, and the location aspect. Every phrase earns its place, and there is 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?

  For a simple, parameterless read-only status tool with no output schema, the description covers what an agent needs to know: that the tool checks installation, running state, and bridge location. Sibling tools are unrelated, and no prerequisites or caveats are necessary for this operation.

  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 description cannot add parameter-level meaning. A score of 4 is the appropriate baseline for a parameterless tool, and the description sufficiently explains the tool's purpose without needing parameter details.

  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 a specific verb ('Check') and identifies the concrete resource: whether the Perssua desktop app is installed, running, and where its integration bridge lives. This clearly differentiates it from the sibling tools, which deal with assistants and sessions.

  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 a clear use context: call this tool to determine the desktop app's installation and running state, and to locate its integration bridge. It does not explicitly mention alternatives or exclusions, but the sibling tools' purposes are clearly different enough that the intended use is evident.

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

• create_session_linkA
  4.3/5.0
  Behavior4/5

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

  The annotations declare readOnlyHint=true, matching the description's non-mutating 'build a link' framing. The description adds valuable behavioral context beyond annotations: the link is activated on click, may include an https launcher when configured, and importantly 'Inline links never auto-submit — the user reviews the prefilled prompt in Perssua.'

  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?

  Three sentences, each earning its place: one for what the tool builds, one for when to use it, and one for the critical non-auto-submit caveat. Information is front-loaded and there is no 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?

  The description covers the tool's purpose, usage context, a key behavioral caveat, and the role of all major parameters. With readOnlyHint=true and no output schema required, this is a complete and well-scoped description for an agent to select and invoke the tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the input schema documents all four parameters. The description names prompt, assistant, and context in the opening sentence but adds little semantic detail beyond what the schema already provides. This is an appropriate baseline-3 score.

  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 specific verb and resource: 'Build a perssua:// deep link...'. It also clarifies the purpose by stating it starts a session with an assistant, prompt, and context when clicked, distinguishing it from start_session even without naming it.

  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 explicitly states when this tool should be used: 'from hosted/remote connectors (ChatGPT, Grok, web chats) where this server cannot reach the user's machine.' This is clear contextual guidance, though it does not explicitly name the alternative (start_session) or state a when-not-to-use condition.

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

• list_assistantsA
  4.3/5.0
  Behavior3/5

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

  Annotations already cover the read-only and non-open-world nature, so the description does not need to restate those. It adds the useful scoping detail that only the user's configured assistants are listed and that results include name and id, but it stays silent on ordering, pagination, or empty-list 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?

  A single, front-loaded sentence that leads with the verb and resource and then explains the purpose. No filler, no repetition of the tool name, and every clause 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 zero-argument, read-only list tool, the description provides the essential return fields and the reason to call it. There is no output schema, but 'name and id' gives an agent enough to invoke and interpret the call successfully.

  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?

  With zero parameters, the schema already carries complete parameter information, so the description does not need to compensate. The mention of returned fields ('name and id') adds relevant context for interpreting the call result.

  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?

  States a specific verb ('List'), a specific resource ('the user's configured Perssua assistants'), and the key returned fields ('name and id'). This makes it easy to distinguish from the sibling tools, which create or start sessions rather than enumerate existing assistants.

  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?

  Implies the right usage moment: call this before starting a session so the correct assistant can be selected. It does not explicitly name alternative tools or state when not to use it, so it falls just short of full guidance.

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

• create_assistantA
  4.5/5.0
  Behavior4/5

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

  Beyond the annotations, the description discloses important behavioral details: knowledge and files become permanent context, they are not part of the first message, a session is opened immediately, and the tool runs on the same machine as the Perssua app. This adds meaningful context without contradicting the annotations.

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

  Conciseness5/5

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

  The description is front-loaded with the core action and then provides structured, numbered pre-call guidance. Every sentence carries useful information, including the environment note about running on the same machine, with no fluff or repetition.

  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 8 parameters and no output schema, the description provides rich context: what to do before calling, how to craft instructions, the permanence of knowledge, and the local-machine runtime. Combined with the fully described schema, an agent has everything needed 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 documents all parameters with 100% coverage, so the baseline is 3. The description adds extra semantic value by clarifying that knowledge and files become permanent assistant context rather than part of the first message, which directly disambiguates knowledge, files, and firstPrompt.

  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: create a new custom assistant in the Perssua desktop app and open a session with it. It also names the key ingredients (name, system-prompt instructions, optional knowledge), clearly distinguishing this from sibling tools like list_assistants and start_session.

  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 unusually concrete usage guidance by requiring a brief user interview before calling and specifying exactly what to ask. It does not explicitly list sibling alternatives or when-not-to-use cases, but the context for when this tool is appropriate is very clear.

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

• start_sessionA
  4.6/5.0
  Behavior4/5

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

  Annotations already indicate readOnly=false and destructive=false, and the description adds meaningful runtime facts: the tool launches a local desktop app, only accepts local text-file paths, and silently skips binary files. It does not cover every side effect like process lifecycle or return behavior, but it goes well beyond the bare annotation profile without contradicting 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?

  Three sentences, each earning its place: the core function, the local-vs-remote boundary, and the file/new-assistant caveats. It is front-loaded with the main purpose and contains no repetition of the title or schema fields.

  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 six optional parameters and no output schema, the description gives enough context to select and invoke it: local execution, remote alternative, file restrictions, and new-assistant alternative. The remaining gap is that it does not describe what the tool returns or what state changes occur after launch, which would be more important without the strong sibling guidance.

  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%, so the baseline is 3. The description adds value by grouping the parameters into a coherent invocation scenario ('optional assistant, initial prompt, free-text context, and text files') and by contributing the binary-file-skip constraint that is not present in the schema. This lifts 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 states a specific verb and resource ('Launch the Perssua desktop app and start a session') and enumerates the optional payloads it accepts. It explicitly distinguishes the tool from create_session_link and create_assistant, so an agent can disambiguate at a glance.

  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 gives explicit when-to-use and when-not-to-use guidance: local same-machine usage vs 'remote/hosted setups use create_session_link instead,' and new-assistant creation routed to create_assistant. This is direct alternative routing rather than leaving the choice to inference.

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