code-synapse

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 discloses that the tool returns a candidate pool and guidance, and is context-free. However, it does not mention side effects, idempotency, or safety implications. More transparency on behavioral traits like read-only or statelessness would improve the score.

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

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

The description is concise and front-loaded with the core purpose. It uses two sentences to convey key information. However, some phrasing ('The CALLING AGENT then picks...') could be streamlined. Overall, it is efficient and avoids redundancy.

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

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

Given two parameters, no output schema, and no annotations, the description covers essential aspects: what the tool returns, how the output should be used, and input constraints. It does not describe the response structure or error cases, but for this complexity level it is adequately complete.

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

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

Schema description coverage is 100%, so baseline 3 applies. The description mentions 'build intent' but does not add significant meaning beyond the schema. The parameter descriptions in the schema are already clear ('what to build, e.g. self-hosted music streaming server'). The description adds minimal value for parameter understanding.

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

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

The description explicitly states the tool's purpose: 'Given a build intent, return a role-tagged CANDIDATE POOL + synergy edges + guidance (NOT a finished blueprint).' It specifies what it does (returns candidates, edges, guidance) and what it does not (finished blueprint), distinguishing it from sibling tools like get_synergy_guide and search_components.

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

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

The description provides clear usage guidance: 'The CALLING AGENT then picks per-role candidates that fit the user's actual hardware/stack...' and 'Server is context-free: do not send user project info.' It instructs on how to process the output and what not to include in input. However, it does not explicitly compare to siblings or specify when to use alternatives.

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

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

No annotations provided; description does not disclose behavioral traits such as read-only nature, error behavior, or effects. Carries full burden but only states 'check' without elaboration on what happens on success/failure.

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

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

Single sentence, no wasted words, front-loaded with the core action and details.

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

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

For a simple tool with one parameter and no output schema, the description adequately states purpose and input. However, it could mention output expectations or behavior when components are not found.

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

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

Schema coverage is 100% with a description example in schema. Description adds minimal value by explaining 'specific component ids' but does not further clarify the array format or constraints beyond the example.

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

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

Description clearly states the verb (Check compatibility/synergy), resource (specific component ids), and provides specifics (role complementarity + co-occurrence). Differentiates from siblings by focusing on synergy check rather than assembly or search.

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

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

No explicit mention of when to use this tool versus siblings; usage context is only implied by the tool name and sibling tool names. Lacks guidance on prerequisites or exclusions.

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

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

No annotations provided; description adds specific behavioral context about fit.status='unknown' meaning fields not yet extracted and advises verifying via README. Does not cover other behaviors like rate limits or auth, but adequate for a read-only search.

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

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

Two sentences; first states action and result, second adds critical nuance. No wasted words. Front-loaded with purpose.

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

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

No output schema, but description mentions return fields (signals with role, protocols, affordance, fit, freshness) and warns about fit.status. Lacks pagination or error info but sufficient for a search tool with one parameter.

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

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

Schema has 100% coverage with description for 'query' parameter. Tool description adds 'by keyword, role, or category', slightly enriching the schema but not substantially. Baseline 3 is appropriate.

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

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

Clearly states verb 'Search', resource 'open-source components', and context 'Code Synapse graph'. Distinguishes from sibling tools assemble_architecture and get_synergy_guide which have different purposes.

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

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

Implies usage for searching by keyword, role, category. No explicit when-to-use or when-not-to-use compared to siblings. Includes a caveat about fit.status but no exclusion criteria.

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