Synap

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

With annotations already declaring openWorldHint=true and non-idempotence, the description still adds real behavioral context beyond them: billing of prompt+completion tokens to the connection's API key, two distinct failure modes (missing key -> error with nothing spent, no balance -> insufficient_credits), no streaming, and no memory between calls. This is exactly the kind of disclosure an agent needs before spending money.

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?

Purpose is front-loaded in the first sentence, followed by usage, cost, failure modes, and return shape in a logical order. It is dense with six sentences, but nearly every sentence carries distinct operational value; only the cost/sibling routing sentence slightly overlaps the usage sentence.

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 paid, non-idempotent inference call with no output schema, the description covers what the agent cannot derive from structured fields: auth requirements, cost model, error semantics, statelessness, and the response payload shape. Nothing material is missing for correct invocation.

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 the baseline is 3, and the description exceeds it by adding the statelessness requirement that forces the agent to resend the full message history each call, plus the return-format mapping (choices[0].message.content, usage). It does not add syntax detail for max_tokens or temperature beyond what the schema already provides.

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 states a specific verb and resource ('Send a conversation to a model on Synap... get the model's reply') and names the concrete capability set (text generation, code, Q&A). It is trivially distinguishable from the sibling tools, which are all read/informational (list models, get model, estimate cost).

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?

It gives explicit when-to-use conditions ('when you need text generated, code written or a question answered') and routes to the alternative 'Call synap_estimate_cost first if the price matters.' The cost caveat ('the only tool here that costs money') sharpens the choice against its free siblings.

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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral context beyond them: it is free, needs no API key, runs no model, is an estimate that may differ from the post-hoc real charge, and errors on auto-routing ids. It also enumerates the returned fields, which matters because there is no output schema.

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?

Four tight sentences, front-loaded with what the tool does, then when to use it, then the return shape and the estimate caveat. The return-field list earns its place precisely because no output schema exists.

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 pure read-only estimation tool with no output schema, the description supplies everything an agent needs: purpose, timing, cost/free status, auth-free nature, return shape, precision caveat, and error condition.

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 all three parameters (model, prompt_tokens, completion_tokens) are already documented with units, minimums, and guidance on using max_tokens for a worst case. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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?

States a precise verb+resource (estimate the cost of a chat completion on Synap) and the input basis (token counts, live price list). It is clearly distinguishable from synap_chat_completion, synap_list_models, and synap_get_model without opening any schema.

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?

Gives explicit usage conditions: use before synap_chat_completion when budget matters, or to compare models for a job. It also names the failure case (auto-routing ids like synap-v1 have no fixed price and error out), which routes the agent correctly for the edge scenario.

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?

Annotations already declare read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them: it states the call is free, requires no API key, and that failures return an error naming the id rather than silently failing. It stops short of describing response shape or rate limits, so 4 rather than 5.

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?

Four short sentences, front-loaded with what is returned and then why/when to use it. Every sentence carries distinct information (content, routing, cost/auth, error behaviour) with no 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?

With no output schema, the description must say what comes back, and it does ('the raw model object, or an error naming the id'). Combined with the auth/cost note and the sibling routing, an agent has everything needed to invoke it correctly.

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% and there is a single required parameter, so the schema already documents that 'model' is the id from synap_list_models. The description adds no syntax, casing, or format detail beyond what the schema states, making this the baseline 3.

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?

States a precise verb and resource ('Return the complete catalogue record for one Synap model') and enumerates the exact fields covered (pricing, limits, parameters, quantisation, retention, readiness). It also explicitly positions itself against the sibling synap_list_models, so an agent can distinguish it without opening either schema.

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?

Gives an explicit trigger ('Use this after synap_list_models when you need details the summary leaves out') and names the alternative tool plus the condition that selects it. No inference is required to choose between the two.

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?

Annotations already declare read-only, idempotent, non-destructive and closed-world, but the description adds substantial context they cannot convey: no API key required, free, safe to call repeatedly, and critically that the list is live so models may appear/disappear between calls. It also documents the return payload shape and the pricing semantics (USD per million prompt/completion tokens, absent for auto-routing ids that bill at the routed model's price).

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?

Front-loaded with purpose, then usage, then behavioral caveats, then the return shape. The inline JSON skeleton is long but justified because no output schema exists. Slightly dense, but nearly every clause carries information an agent needs before calling.

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?

With no output schema and annotations covering only safety, the description fully compensates: it describes the response envelope and each field, the pricing units, the auto-routing pricing exception, and the live-list volatility. Nothing needed to select and call this tool correctly is missing.

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%, and the single optional `query` parameter is fully documented there (case-insensitive, matched against id/name/capability, with examples). The description adds no meaning beyond the schema for this parameter, so the baseline of 3 applies.

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?

States a specific verb and resource ('List the models Synap serves right now') and immediately enumerates the returned attributes: price per million tokens, context window, and capability. It is clearly distinguishable from synap_chat_completion (which consumes a model id) and synap_get_model (which drills into one model).

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?

Gives explicit when-to-use conditions: choose a model id before calling synap_chat_completion, or compare prices. It also routes the agent to the alternative, synap_get_model, for the full field set of a single model, so both the positive and the negative case are covered.

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