Server Quality Checklist

Tool Scores

• pin.analyzeC
  2.3/5.0
  Behavior3/5

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

  Annotations already declare readOnly, non-destructive, and idempotent behavior, so the safety profile is covered. The description adds a stylistic note ('Decision evidence—not a dump') hinting at concise output, but it doesn't disclose how the three modes are triggered or whether outputs are structured.

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

  Conciseness3/5

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

  The description is very brief (around 15 words), which is economical, but the content is cryptic and uses jargon without context. The list structure is confusing and not front-loaded with a clear action statement.

  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?

  There is no output schema, so the description must explain return values. The phrase 'Decision evidence—not a dump' is too vague, and the tool supports multiple modes without describing what each mode returns or how they differ.

  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 an empty schema, the description must explain what context or implicit inputs are needed, but it only mentions 'evidenceSetId' without elaboration and lists three modes with no way to select them. This leaves the agent guessing how to invoke the tool.

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

  Purpose2/5

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

  The description lists three capabilities ('EvidenceBrief (knownFacts/gaps/evidenceSetId), documentation gaps, or coverage compare') but never states a clear verb or resource. The name 'analyze' is generic, and it overlaps with sibling pin.compare for coverage comparison, making it unclear what uniquely identifies this tool.

  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 explicit when-to-use guidance, no mention of alternatives, and no exclusions. Siblings like pin.compare, pin.prove, and pin.verify suggest overlapping functions, but the description doesn't clarify boundaries or contexts.

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

• pin.proveA
  3.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, making safety clear. The description adds behavioral context by specifying that the evidence pack includes a slice, path, line, full SHA, content hash, handle, and verify next-step, giving insight into what the tool produces beyond 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.

  Conciseness4/5

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

  The description is a single sentence that front-loads 'Primary product tool' and packs multiple pieces of information into a compact form. It has no filler, though the heavy jargon may reduce accessibility. Overall, it is concise and well-structured for the information it conveys.

  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 5 parameters, no output schema, and no parameter descriptions, this one-line description is incomplete. It does not explain the return format, how to formulate a claim, the meaning of 'verify next-step,' or any prerequisites. The tool's complexity is under-explained, leaving an agent with insufficient information to invoke it correctly in all cases.

  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 description coverage is 0%, and the description does not explain the five parameters (claim, lineStart, lineEnd, repository, sourcePath). Terms like 'slice' and 'path' hint at line and sourcePath but are not explicit mappings, leaving the parameter meanings largely undocumented. This is insufficient compensation for the lack of schema descriptions.

  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 says 'Primary product tool: one-path evidence pack' and lists components, indicating it produces an evidence pack for factual claims. The phrase 'Prefer for every factual claim' clarifies its intended use. However, the language is jargon-heavy and lacks a simple verb phrase, making it less immediately clear than a straightforward verb+resource description.

  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 instruction 'Prefer for every factual claim' gives clear guidance on when to use this tool, implying it is the default choice for factual claims. It distinguishes the tool from siblings by positioning it as the go-to for factual assertions, though it does not explicitly name alternatives or exclusions.

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

• pin.prove_setA
  3.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable behavioral constraints: supports 1-8 paths and multi-repo, which are not fully captured by annotations. It also implies a workflow (Next: pin.verify_set) without contradicting any annotation.

  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 extremely concise: two sentences that pack purpose, usage, and next-step guidance. Every phrase earns its place—'Multi-cite evidence set' defines the output, '(1–8 paths, multi-repo OK)' adds key constraints, and the next-step pointer is a clean workflow hint. No fluff.

  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?

  Given the tool has one nested parameter and no output schema, the description should clarify what the tool returns or how it behaves beyond the annotations. It does not mention return values or the meaning of 'prove_set' (e.g., does it output a proof object?). The workflow hint is helpful, but the missing return semantics leave a gap for an agent trying to use the tool correctly.

  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 description provides no additional meaning for the 'items' parameter beyond restating the min/max bounds already in the schema ('1–8 paths' directly mirrors minItems/maxItems). It does not explain fields like repository, sourcePath, claim, or line numbers, and schema coverage is 0%, so the description fails to compensate for the low coverage.

  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 indicates this tool creates a multi-cite evidence set with 1-8 paths, and the mention of 'Next: pin.verify_set' differentiates it from the verify workflow. However, it lacks an explicit verb like 'creates' or 'pins', leaving some ambiguity about the exact action.

  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 explicitly states when to use it ('Use when an answer needs several citations') and hints at the next step (pin.verify_set), providing workflow context. It does not explicitly mention when not to use it, but the 'use when' is sufficient and distinguishes it from sibling tools like pin.prove.

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

• pin.get_docA
  3.8/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing it as a safe read operation. The description adds context that it reads 'committed' pages and returns a 'pinned evidence slice with full SHA,' which is useful beyond 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 two sentences long, front-loaded with the primary purpose, and contains no wasted words. The alternative guidance is included efficiently.

  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, read-only tool with only two parameters and no output schema, the description is mostly complete. It covers what the tool does, the 'committed' aspect, the pinned evidence slice with SHA, and provides a key alternative. It could mention return format or error cases, but these are not critical given the simplicity.

  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 description coverage is 0%, and the description does not explain what 'repository' or 'sourcePath' mean or how they should be formatted. The parameter names are somewhat self-explanatory, but the description fails to add any additional semantics, leaving the agent without guidance on valid values or expected format.

  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 reads one committed documentation page and produces a pinned evidence slice with full SHA. It distinguishes itself from pin.prove by noting that prove is preferred for claims, though it doesn't explicitly differentiate from pin.read.

  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?

  Provides an explicit alternative: 'Prefer pin.prove for claims,' which tells the agent when not to use this tool. However, it lacks detailed guidance on when to use this tool over pin.read or other siblings, only implying its use for documentation pages.

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

• pin.inspectA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds a specific behavioral trait: 'status shows dirty work excluded from evidence,' which explains a filtering behavior. It does not detail return formats or pagination, but the annotation coverage lowers the burden.

  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 the core purpose and a useful behavioral note. No wasted words.

  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?

  With three parameters, five operations, and no output schema, the description is relatively brief. It names the operations but omits details about what each returns (e.g., manifests vs tests) and does not explain the limit parameter. Annotations improve safety understanding, but an agent would benefit from more detail.

  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 carries the burden. It explains the operation values (status, commits, manifests, tests, changes) and adds context for 'status', but does not explain the 'repository' or 'limit' parameters. Partial compensation for missing schema 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 inspects HEAD-pinned status, commits, manifests, tests, or recent changes, with a specific verb and resource. It distinguishes from siblings by listing its unique operations (e.g., status, commits) compared to read/prove/analyze functions.

  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 inspecting repository state but does not explicitly state when to use it over sibling tools like pin.read or pin.prove. The note about status excluding dirty work provides context for one operation, but no when-not-to-use guidance or alternative references.

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

• pin.readA
  3.9/5.0
  Behavior4/5

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

  Annotations already establish safety (readOnly, idempotent, non-destructive). The description adds 'HEAD-only' and 'Sensitive paths blocked,' which are behavioral constraints beyond annotations, giving the agent useful expectations about what will or won't succeed.

  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, front-loaded with the primary purpose. No fluff; every clause adds value (action, constraints, alternative). Ideal size for a focused tool description.

  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?

  No output schema exists, so the description should clarify return values, but it only vaguely references 'full SHA.' It also omits line range behavior, error handling for sensitive paths, and optionality of lineStart/lineEnd. With 4 parameters and no output schema, this description leaves significant gaps for an agent to safely invoke the tool.

  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 descriptions are entirely absent (0% coverage), so the description must carry parameter meaning. It mentions 'path, lines, full SHA' which hints at sourcePath and lineStart/lineEnd, but does not explain their semantics, ordering, defaults, or how 'full SHA' relates to parameters. This is insufficient for a tool with 4 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 clearly states the tool reads a HEAD-only source slice, specifying the resource (source code) and scope (path, lines, full SHA). It differentiates from siblings by explicitly recommending pin.prove for claim-making, indicating pin.read is for direct reading.

  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?

  Provides a clear alternative: 'Prefer pin.prove when making a claim' tells when not to use this tool. It also notes sensitive paths are blocked, implying a constraint on usage. However, it does not elaborate on when to choose pin.read over other siblings like pin.inspect or pin.get_doc.

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

• pin.verify_setA
  3.9/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about batch size (already in schema) and source, but does not disclose additional behavioral nuances like failure handling or evidenceSetId semantics. No contradiction with 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 a single, front-loaded sentence with no redundant wording. It efficiently communicates the core action, limitations, and use cases, earning full marks for conciseness.

  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 moderate complexity, strong annotations, and no output schema, the description provides adequate context: purpose, input source, and when to use. It does not explain return values, but this is likely inferable from the verification context. A bit more detail on output or failure behavior could push it to a 5.

  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 description coverage is 0%, so the description must compensate. It only loosely implies that 'items' contains citations and mentions 'from pin.prove_set or a pack', but it never explains individual fields (sha, sourcePath, mustContain) or the evidenceSetId parameter. This is insufficient to fully guide parameter usage.

  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 identifies the action ('Batch re-check'), the resource ('citations'), and a specific scope ('up to 8'). It distinguishes itself from sibling tools by positioning as the batch version of pin.verify and naming input sources (prove_set or pack) and target use cases (multi-repo, CI).

  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?

  Provides clear context for when to use the tool: multi-repo answers and CI citation gates, and specifies input source (prove_set or pack). However, it does not explicitly name alternatives (e.g., pin.verify for single citation) or state exclusions, so it lacks the 'when not to use' component.

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

• pin.search_docsA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the key behavioral context that results are 'documentation candidates (not claims)' — i.e., they are unverified and require subsequent prove/verify steps. This goes beyond the annotations and informs the agent about result reliability.

  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. It front-loads the core purpose and immediately adds a critical usage constraint. Every sentence earns its place.

  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?

  Given there is no output schema, the description should explain what the tool returns. It says 'documentation candidates' but does not specify the result format, pagination, or how to interpret results. The repository parameter is also unexplained. Overall, the description is useful but incomplete for a search tool with no output schema.

  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 description coverage is 0%, so the description must compensate. It does not explain 'query' or 'repository' at all. While 'query' is self-explanatory, 'repository' is ambiguous (repository name? path? filter scope?) and the description adds no clarification.

  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 purpose: 'Find documentation candidates (not claims).' This uses a specific verb and resource, and the parenthetical distinguishes it from claim-verification tools like pin.prove and pin.verify. It also differentiates from pin.search_code by focusing on documentation.

  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 clear workflow guidance: 'Before any factual assertion call pin.prove or pin.prove_set, then pin.verify.' This tells when to use this tool in a larger pipeline. However, it does not explicitly mention alternatives like pin.search_code or state when not to use this tool, so it falls short of a 5.

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

• pin.verifyA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying use of 'git show' and disclosing the output (HEAD match and claimVerdict), which goes beyond the annotations. No contradiction.

  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, information-dense sentence. It front-loads the core purpose ('Close the prove loop') and packs essential details (git show, mustContain, output fields) without wasted words.

  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 covers the primary action and output (HEAD match and claimVerdict), and annotations cover safety. However, with no output schema and five parameters, it leaves gaps: the meaning of 'line' is unclear, how mustContain interacts with claim-text is vague, and repository handling is not explained. It is adequate for a simple tool but not fully complete.

  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 description coverage is 0%, so the description must compensate. It introduces 'path@SHA' (suggesting sourcePath and sha) and 'mustContain' purpose, but it fails to explain the 'repository' and 'line' parameters. Given five parameters, this is insufficient—line has no hint 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 a specific action: 're-check path@SHA with git show' with an optional mustContain for claim-text. It distinguishes pin.verify from siblings by framing it as 'Close the prove loop' and reporting HEAD match and claimVerdict, which aligns with verification rather than proving or setting.

  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 'Close the prove loop' implies this is used after pin.prove to re-check a pinned path at a given SHA. It provides clear context for when to use it, though it doesn't explicitly mention when not to use it or name alternative tools.

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

• pin.compareA
  4.2/5.0
  Behavior4/5

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

  Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it produces 'changed paths' as output and is 'bounded' in scope, which clarifies the nature of the operation beyond the annotations. No contradiction with 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 two concise sentences: the first states the core action and the second adds a qualifier and exclusion. Every word earns its place, with no filler or 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 simple diff tool, the description, combined with annotations and schema, provides sufficient context for an agent to select and invoke it. It explains the output at a high level (changed paths) and distinguishes from semantic search. The absence of an explicit output format is not critical given the tool's simplicity, but a bit more detail on the return value would improve completeness.

  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 explains that the tool compares 'two hex revisions,' which covers the format and intent of the base and head parameters. However, the repository parameter is not mentioned at all, and with 0% schema description coverage, the description does not fully compensate. The property names are self-explanatory, but the description could be more explicit about all three 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 states a specific verb and resource: 'Diff changed paths between two hex revisions.' It clearly distinguishes the tool from siblings like pin.search_docs and pin.search_code by explicitly noting it is 'not semantic search.' This makes the tool's purpose unmistakable.

  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 clear context ('Bounded change evidence for reviews') and an explicit exclusion ('not semantic search'), which helps the agent understand when to use this tool versus semantic search tools. However, it does not explicitly name alternative sibling tools or provide a direct when-to-use/when-not-to-use contrast, leaving a minor gap.

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

• pin.catalogA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns metadata like HEAD SHAs and doc counts, and explicitly states it does not claim content, which is additional behavioral context beyond 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?

  Three short, front-loaded sentences deliver the essential information (call first, what it does, what it returns, and its precedence) with no filler or excessive detail. 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?

  For a simple read-only listing tool, the description covers the core functionality and usage context. However, it omits explanation of the view parameter and does not describe the output shape (though no output schema exists), leaving a minor gap in completeness.

  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 one optional enum parameter 'view' with values repositories, sync, and stale. The description mentions 'stale' in the overview but does not explain the meaning or distinction of the three view options. With 0% schema description coverage, the description fails to compensate for 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 discovers registered Git roots and specifies the returned metadata (HEAD SHAs, doc counts, stale). The phrase 'Not a content claim' further clarifies its scope, distinguishing it from content retrieval tools like search or prove.

  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 'Call first' and 'Use before search/prove', establishing precedence among siblings. It also implies when not to use it (when content is needed) by stating it is not a content claim.

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

• pin.search_codeA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context: that it searches at HEAD specifically and that results are candidates, not final claims. This goes beyond annotations but could mention edge cases (e.g., behavior on large repos).

  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, front-loaded with the core purpose and immediately followed by usage guidance. 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?

  Given the absence of an output schema, the description could mention what is returned (e.g., list of matches or file paths), but the workflow context and candidate concept sufficiently frame the tool's role. It is complete for tool selection but slightly lacking in return-value transparency.

  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 description coverage is 0%, and the description does not explain the 'query' or 'repository' parameters beyond their obvious meanings. It only implies query is a search term, but no format, scope, or default behavior is clarified. 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.

  Purpose5/5

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

  The description uses specific verb 'Find' with resource 'code candidates via git grep at HEAD', clearly distinguishing it from other tools like search_docs and the prove/verify family. It precisely states what the tool does.

  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 instructs when to use the tool ('Never treat hits as final claims') and provides explicit alternatives: 'pin.prove then pin.verify (or prove_set/verify_set)'. This is clear guidance on the workflow relationship.

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