canton-ccpedia

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

Annotations declare readOnlyHint=false and openWorldHint=true, and the description is consistent, since proxying can invoke arbitrary downstream tools. It adds real context beyond annotations: it discloses that the call is proxied, that the result is returned, and the eligibility limits on target servers. It stops short of noting error behavior 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.

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

Front-loads the core action and the discovery pointer in the first sentence, then adds constraints. The 'Canton-only' trailing fragment is clipped but functional; overall it is tight and earns most of its length.

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 exists, yet the description states it returns the proxied result, and it covers the main caveat (fallback connect instructions for ineligible servers). For a 3-param federation tool this is largely complete, with only error/return-format specifics 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%, so the schema already documents all three parameters. The description reinforces the server param by pointing to list_canton_mcps as the id source, but adds no syntax or format guidance beyond that. 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?

States a specific verb (federate a tool call) and resource (another Canton MCP server), and explicitly routes to the sibling list_canton_mcps for discovery. An agent can distinguish this proxy from the dozens of content-retrieval siblings without opening a 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 concrete when-to-use context via list_canton_mcps and states the operative exclusion: only free/hosted/no-auth MCPs can be proxied, while local or paid ones return connect instructions. It lacks an explicit 'use X instead for Y' alternative, but the constraints effectively define the eligible case.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the three possible result states (DEPRECATED with replacement, CURRENT, NOT_FOUND) and the prose-scanning mode that reports every deprecated item mentioned.

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 the core purpose, then scope exclusions, usage imperative, and output states. Dense and information-bearing, though slightly redundant between the description's prose-scan sentence and the schema's identical note.

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 exists, and the description supplies the return-value taxonomy (DEPRECATED/CURRENT/NOT_FOUND with replacement info), scope, and usage imperative. An agent has everything needed to select and call 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 coverage is 100%, so the baseline is 3; the schema already explains the name parameter including the prose-scanning behavior. The description reinforces that the input may be a single name or a block of prose and clarifies the resulting scan semantics, adding modest value beyond the schema.

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 (check) and resource (Canton/Daml toolchain item: CLI, SDK package, command) with concrete examples. It explicitly distinguishes itself from the sibling list_deprecations by operating on a single named item or prose block, and from out-of-scope checkers ('not a general npm/pip deprecation checker').

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 guidance ('ALWAYS call before recommending any Canton tool or package') and scope exclusions. It does not explicitly name the sibling alternative (list_deprecations) or state when not to use it, 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.

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds useful context about what gets assembled (view/reply/participant counts, per-term message counts, first reply) and explicitly rules out sentiment analysis, but says nothing about matching thresholds, coverage limits, or empty-result behaviour.

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?

A single dense sentence with no filler, and the core purpose is front-loaded. It is somewhat overloaded – three distinct behaviours and a scope disclaimer squeezed into one sentence – but nothing is wasteful.

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 carries the burden of explaining returns, and it does so at a reasonable level (threads with engagement metrics, message counts, first reply). Minor gaps remain around result limits and what happens when no thread matches, but an agent can call 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?

There is a single parameter with 100% schema coverage, so the baseline is high. The description adds meaning by explaining that matching is semantic ('match it best by meaning') for forums and term-based for the mailing list, which tells the agent more about how 'topic' is interpreted than the bare schema does.

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 names a specific composite resource – forum threads matched by meaning, mailing-list threads matched by term mentions, plus the first reply on the top thread – so the agent knows this is a roundup rather than a raw search. It does not name the sibling search tools (search_community, search_mailing_list) it could be confused with, so differentiation is implied rather than stated.

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 clause 'Not sentiment-analysis; a structured roundup the caller can summarise' sets expectations and implicitly tells the agent this is for overall community read rather than per-document lookup, but there is no explicit when-to-use or when-to-prefer-search_community guidance. A reader must infer the boundary from the return-shape description.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add semantics. It does that by disclosing a non-obvious data limitation: merged/withdrawn/rejected outcomes are not distinguished and no close dates are stored, which directly affects how results must be interpreted.

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 the verb and scope, and every clause contributes (metrics list, limitation caveat, domain scope, use case). It is a single heavily nested sentence near the upper limit of comfortable density, but nothing is padding.

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 exists, so the description must describe return content, and it does by naming each aggregate it produces. Combined with the caveat about undistinguished close outcomes and the Canton scope, an agent has enough to call it and to interpret the result.

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 window_days already documents its 7-365 range and default of 90. The description only says aggregation happens 'over a window' without adding syntax or edge-case behavior 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 specific verb (aggregate) and resource (governance throughput) and then enumerates the exact metrics produced: CIP status changes, cip-vote/cip-discuss mailing volume, and dev-fund proposals. This lets an agent separate it from per-item siblings such as get_cip_history, list_governance_votes, and get_dev_fund_activity 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?

Provides a concrete triggering question ('what governance has shipped this quarter?') and scopes itself as Canton-specific, which is real usage context. However, it names no alternative tool and gives no explicit when-not-to-use guidance, so it stops short of full routing.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds the useful constraint that the target is always Canton, but says nothing about output format or lookup behavior. With annotations doing the heavy lifting, a 3 is appropriate.

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?

Three sentences, front-loaded with the core purpose, then scope, then the routing alternative. No filler; every sentence earns its place.

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 exists, so the description carries some burden for return expectations, which it does not describe. However, for a simple read-only concept-mapping lookup with a fully documented single parameter and complete routing guidance, an agent has enough 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% for the single 'concept' parameter, so the schema already carries the semantics. The description's example list duplicates the schema's own examples rather than adding new meaning, so 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 specific verb (Map) and resource (EVM concept → Canton equivalent), gives concrete examples, and names the direction constraint ('target is always Canton'). It clearly distinguishes itself from the adjacent learning-path sibling.

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?

Explicitly scopes usage to 'single concept-to-concept translations' and routes the alternative case to get_started_guide for 'a full EVM-to-Canton learning path'. This is a textbook when-to-use / when-to-use-something-else split.

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 establish readOnly, idempotent, non-destructive, and closed-world behavior. The description adds real value beyond that by disclosing the two corpora searched and the relative breadth versus find_similar_projects, which is behavioral context the annotations cannot convey. It stops short of describing result shape or ordering, which keeps it from a 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?

Front-loaded with the core action and scoping, and each sentence contributes something (scope, sibling contrast, domain, motivation). It is slightly list-like in the colon construction but waste-free overall.

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 read-only, one-parameter search tool with full annotation coverage and no output schema, the description covers what is searched and why. The main remaining gap is that 'looks similar' is never qualified (semantic vs. keyword matching, ranking, or result volume), which an agent would benefit from knowing.

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?

Only one parameter with 100% schema description coverage ('One-paragraph project idea or capability description'), so the schema already carries the semantics. The description restates it as 'project/proposal idea' without adding format, length, or quality guidance, which is the expected baseline when the schema does the work.

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+resource ('find existing Canton ecosystem projects + dev-fund proposals that look similar') and immediately scopes it to BOTH the dev-fund proposals corpus and ecosystem_projects. It explicitly distinguishes itself from the sibling find_similar_projects, so an agent can pick between them 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 clear context ('Cuts manual cross-reference research before submitting a new proposal') and names an alternative (find_similar_projects) with the condition that separates them. It does not address the overlap with other siblings like find_duplicate_proposals, so exclusions are partial rather than complete.

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, closed-world behavior, so the safety bar is met. The description adds real behavioral context beyond that: the exact nature of the return (full chain plus per-prerequisite status) and the accepted ID formats, which an agent needs to interpret results.

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 the core action and return value, followed by input formats, scope, and usage cue. Four sentences, each carrying distinct information, with no padding.

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 exists, and the description fully compensates by describing what is returned (the prerequisite chain with current statuses). Combined with annotations covering the safety profile and the schema documenting the single parameter, an agent has everything needed to call 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 the single parameter's format examples ('CIP-0112', '0112', 'PR-203') are already spelled out in the schema. The description largely restates those accepted formats rather than adding new semantics, 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 specific verb ('Walk the CIP requires: graph') and resource, and precisely defines the output: the chain of prerequisites that must reach Final before the starting proposal is implementable. An agent can distinguish this from get_cip or ecosystem_dependency_graph 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 a clear when-to-use cue ('planning around a CIP that hasn't shipped yet') and a scope constraint ('Canton governance only'). It stops short of naming an explicit alternative sibling for related dependency questions, so it is strong context rather than full routing guidance.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral value beyond that by describing the return shape (counts per surface plus the most recent doc-page and forum statement), which matters since 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?

Three tight sentences: purpose, return shape, and sibling differentiation. Every sentence earns its place and the core purpose is front-loaded.

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 carries the return-value burden and does so reasonably (counts per surface plus latest doc/forum statements). It leaves minor gaps, such as whether a GitHub statement is also returned or how mismatches are flagged, but is largely complete for a single-parameter read tool.

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?

Only one parameter with 100% schema description coverage, so the schema fully documents 'topic'. The description adds the notion that the topic is cross-checked across three surfaces, but no format or syntax detail beyond the schema. 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?

States a specific verb and resource (find contradictions between docs, forum and GitHub on a topic) and explicitly distinguishes itself from the sibling get_kb_drift. An agent can tell it apart from get_kb_drift 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?

Names the alternative (get_kb_drift) and characterizes its scope (compares foundation_kb to live releases), which gives clear context for choosing this tool. It stops short of an explicit when-to-use/when-not statement, so it does not reach 5.

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 readOnly, idempotent, non-destructive behavior, so safety is covered. The description adds substantive context beyond that: the return shape ('top 3 matches each from forum and github', dated) and the domain constraint ('Canton-specific'). It stops short of discussing match confidence or what happens on zero results, so a 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?

Front-loads the purpose and the key input, then packs exclusions, scope, and return format into a dense but readable block. Every clause carries information; it is slightly long but not wasteful.

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 supplies the return format itself (top 3 per source, dated, forum + github), plus input requirements and scope. An agent has everything needed to invoke and interpret results 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 coverage is 100%, so the baseline is 3, but the description earns extra credit by giving concrete error_text examples (TOPOLOGY_TOO_MANY_PENDING_TOPOLOGY_TRANSACTIONS, ValidatorLicense) that clarify what kind of literal input is expected. It doesn't document the limit parameter, but the schema already does.

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 ('diagnose' an 'ERROR MESSAGE, stack trace, or error code') and scopes it to Canton/Daml/Splice, which clearly distinguishes it from generic search siblings. An agent can tell it apart from semantic_search 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 explicit when-to-use (literal error string or code) and when-NOT-to-use ('do NOT use it for symptom descriptions with no error text'), naming the alternative tool semantic_search for the excluded case. Nothing is left to inference.

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 readOnly, idempotent, non-destructive, and closed-world (openWorldHint=false), and the description's 'Canton-specific' note is consistent with the closed-world hint. It adds no further behavioral detail such as result shape, depth of the graph, or any limits, so with annotations carrying the safety profile a 3 is appropriate.

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-loads the core operation in the first sentence and reinforces it with a concrete question. 'building a quick dependency picture' is mildly redundant filler, but there is no wasted framing overall.

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 single-parameter read-only lookup with full schema coverage and rich annotations, the description supplies enough to invoke it correctly. The only residual gap is that, absent an output schema, the shape of the returned dependency picture is undefined.

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% for the single 'topic' parameter, so the schema already documents it fully. The description's phrase 'matching a topic' adds no syntax, format, or matching semantics beyond what the schema provides; 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 specific verb ('map') and resource ('ecosystem_projects ... to the SDK versions and repos they appear alongside'), which clearly conveys the dependency-graph operation. It distinguishes itself from list-style siblings like list_ecosystem_projects by emphasizing the cross-linking, though it doesn't name any sibling explicitly.

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 quoted use case ('if I build with X SDK version, who else is on it?') gives an agent a concrete triggering scenario, and 'Canton-specific' scopes it to the relevant ecosystem. It stops short of naming alternatives or stating when not to use it.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavior beyond that: the retrieval strategy (match on name+category first, fall back to description) and the Canton-only scope, which affects coverage expectations for the agent.

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 tight sentences with no filler; the core action is front-loaded and the matching/ranking caveat follows. Every clause carries information.

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 usefully explains the return shape (best matches) and ranking fallback, and scopes the data source. It is nearly complete for a simple search tool, though it stops short of noting result ordering or empty-result behavior.

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 both the pattern examples and the limit default/max are already documented in the schema. The description restates that the pattern spans name, category, and description, which adds little beyond the schema and says nothing about limit, so the 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?

States a specific verb (pattern-search) and resource (Featured Apps catalogue) plus the fields searched (name, category, description), which is more than the name alone conveys. It does not, however, name or distinguish itself from obvious siblings like list_featured_apps or semantic_search, leaving the agent to infer the boundary.

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 phrase "by free-text query" and "Canton-specific" imply when this tool applies (fuzzy/partial matching within the Canton Featured Apps set), but there is no explicit statement of when to prefer it over list_featured_apps or the generic search/semantic_search tools. Usage is left to inference.

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 it read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds meaningful context beyond that: the retrieval mechanism (exact title/body words plus semantic meaning over the CIP index) and the Canton-specific restriction, which tells the agent about recall behavior and scope.

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 short sentences, zero filler, and the core action is front-loaded before the use case. Every clause carries signal (retrieval method, scope, intent).

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 one-parameter read-only lookup tool with full annotation coverage and no output schema, the description is nearly sufficient. It explains purpose, scope, and search method; the only minor gap is not stating explicitly what shape the matches come back as, though with no output schema that is a small omission.

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% with a single 'feature' parameter already documented and exampled in the schema. The description restates the input concept but adds no syntax, formatting, or constraint detail beyond what the schema provides, so 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 specific verb (find) and resource (the matching CIP) with scope qualifiers: Canton features/capabilities, searched over titles, bodies, and semantic meaning. This distinguishes it from siblings like list_cips (enumerate all) and get_cip (fetch one), which the agent can infer from the framing.

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 a clear trigger: 'Use to answer "is there a CIP for X?"', which frames the lookup intent well. It does not, however, name alternatives such as semantic_search or list_cips, so the agent must infer that those are not the right fit.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond them – the AND-combination of code-block presence and topic match – but does not say how the keyword is matched (case sensitivity, substring vs token) or that results only come from forum posts already fetched.

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 short, front-loaded sentences with zero filler: the first states purpose, the second states the filtering mechanism and domain scope. Nothing is repeated from the schema.

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 read-only, three-parameter, no-output-schema search tool, the definition is nearly complete; the schema even documents that the response echoes the full count and offset for paging. The only gap is that the description never describes the returned snippet/posts shape or ordering.

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 of 3 applies; topic, limit (default 5, max 15), and offset/paging are all documented in the schema. The description adds only that topic drives a keyword match, not the matching semantics.

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 names a specific verb+resource ('Find Canton/Daml code snippets in forum posts') and scopes it to a topic keyword, which clearly separates it from generic search tools. It does not name a specific sibling alternative (e.g. search_community), so it stops short of full differentiation.

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?

Usage is implied by the filter logic ('rendered HTML contains <pre> or <code> blocks AND matches the topic keyword') and the 'Canton-specific' note scopes it to that ecosystem. There is no explicit when-to-use / when-not guidance versus semantically similar siblings like search_community, semantic_search, or search.

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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine behavioral context by disclosing the mechanism ('Lightweight heuristic: overlap of tags + adjacent categories'), warning the agent that results are heuristic rather than exhaustive. It does not cover output shape or ranking, keeping it below 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?

Three short, front-loaded sentences with no filler; the core action and the heuristic are stated up front. 'Canton-specific' is mildly redundant given the ecosystem framing but costs little.

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?

A simple read-only, single-parameter, no-output-schema tool; the description explains the intent and the heuristic basis, which is enough for correct invocation. Only the absence of a steer toward which sibling to prefer leaves a small gap.

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 single 'project' parameter is already documented. The description only restates that input is one Canton project, adding no format or slug-syntax detail beyond the schema. Baseline 3 is correct.

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+resource ('find others with complementary tags/category that could plug in') and pins the scope to the Canton ecosystem. The word 'complementary' implicitly distinguishes it from find_similar_projects, though it never names that sibling explicitly.

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 'Given one Canton ecosystem project' framing gives implied usage, and 'could plug in' hints at the collaboration use case, but there is no explicit when-to-use, when-not, or named alternative (e.g., vs find_similar_projects or detect_builder_overlap).

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, closed-world), but the description adds substantial behavioural context beyond that: it enumerates and interprets each relation type, discloses that overlap is a lead rather than a verdict and that possible-overlap is frequently wrong, and states which relations are excluded by default.

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?

Three dense sentences, front-loaded with the purpose before the mode and relation semantics. The caveat sentences earn their place, though the closing tangent about overlap reliability and the trailing 'Canton-specific' are slightly loose.

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 exists, yet the description explains what each returned group contains (relation type, confidence, the numbers behind it) and how paging/counting behaves, and all six parameters are documented in the schema. An agent has everything needed to call and interpret it.

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%, so the baseline is 3, but the description adds genuine meaning: it explains that `number` switches the whole output mode to neighbour listing, describes the Dev-Fund-Navigator default relation set versus the opt-in relations, and notes that min_similarity defaults are validated thresholds.

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 (find Canton Dev Fund proposals that duplicate, re-file or overlap) and names the comparison basis (meaning plus identical text, title, author, organization). It is clearly distinguishable from neighbours like detect_builder_overlap, find_similar_projects and get_proposal.

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?

Explicitly spells out the two modes: without a number it lists groups, with a number it lists the closest proposals to that one with evidence. It also states the default filtering (only groups with an open proposal) and when the softer relations like amendments and same-applicant relations are returned (only when asked for).

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 the safe, idempotent, closed-world read profile, so the bar is lower. The description still adds real context by disclosing the ranking inputs (topic-matched forum activity plus overall forum/GitHub volume of the author) and the source corpus (CCPEDIA), which helps the agent interpret results. It omits any return-shape or limit-related behavior.

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?

A single front-loaded sentence that earns most of its words by explaining the ranking mechanism. 'Canton-specific' is mildly redundant given 'Canton experts', but there is no filler or padding.

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 2-parameter read-only tool whose annotations cover the safety profile, the description is nearly sufficient. With no output schema, it does not describe what the ranked result looks like (e.g., authors with scores), which is the one remaining gap.

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 both 'topic' and 'limit' (default 5, max 15) are already documented in the schema. The description adds no syntax, format, or scoping detail beyond what the schema provides, 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 specific verb (Rank) and resource (likely Canton experts on a topic) and even names the ranking basis (topic-matched forum activity plus overall forum/GitHub volume). No sibling performs expert ranking, so the agent can select it decisively. 'Canton-specific' further scopes the domain.

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?

Usage is implied by the wording ('Rank likely Canton experts on a topic'), but there is no explicit when-to-use/when-not statement and no alternative tool named. An agent can infer the trigger, but must do so itself.

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 establish read-only, idempotent, non-destructive behavior, and the description adds the traits annotations cannot express: what the result set is composed of, that it returns no fixes/solutions/config, and that it returns nothing at all when no open issue matches. Empty-result and negative-output disclosure is exactly the context an agent needs before calling.

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 the core purpose, then exclusions, then routing. Dense but every clause carries routing or scope information. It is a single heavy run-on block rather than cleanly separated sentences, which slightly reduces scannability.

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 convey what comes back, and it does: unresolved forum threads plus open GitHub issues, with an explicit empty-result case. Together with the fully documented 2-param schema and read-only annotations, an agent has everything needed to call this 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%, so 'description' and 'limit' are already fully documented in the schema, including the not-a-stack-trace guidance and the max-15 per-source cap. The description adds only the phrase 'free-text description', so the schema does the heavy lifting and 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 specific verb+resource with explicit scope: 'surface known UNRESOLVED problems' and enumerates the exact corpus ('forum threads with zero replies but high views, plus open GitHub issues'). This is clearly distinguished from sibling search tools like search_github_issues and semantic_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?

Explicit when/when-not routing: use it to answer 'is anyone else hitting this?', do NOT use it for 'how do I fix / configure / why does X happen', where it names the alternative path (semantic_search then get_doc). The schema reinforces with a pointer to diagnose_error for stack traces.

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 cover the safety profile (readOnly, idempotent, closed-world), so the description's value-add is the ranking/selection heuristic: results are by 'top-volume' authors who are only 'likely maintainers', which warns the agent the output is a heuristic signal, not authoritative. It still says nothing about result count, ranking tie-breaks, or time window.

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?

Three short sentences, front-loaded with the action and resource, and the 'Canton-specific' clause earns its place as a scope limiter against broader search siblings. No padding or repetition.

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 carry the return-shape burden but only says 'posts' – no indication of result count, fields, or ordering, which matters for a ranking-based retrieval tool. The when-to-use and scope coverage is good, so this is adequate but with a visible gap.

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?

There is a single required parameter and schema description coverage is 100%, with the schema itself supplying examples ('topology', 'wallet', 'DAR upload'). The description only restates 'on a topic' and adds no format or matching semantics, so 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 specific verb (surface) and resource (forum/mailing posts authored by top-volume Canton contributors) plus the scoping rationale (likely maintainers). It is clearly distinguishable from generic siblings like search_community or get_discussion, though it never names an alternative explicitly.

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?

'Use when you want to weight expert voices over the general forum' gives a concrete selection condition and implicitly contrasts with general forum search tools. It lacks an explicit when-not / named-alternative statement, so it stops 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.

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond them: the matching is lexical so weak fits are flagged, most proposals never declared an RFP, and it returns both declaring proposals and text-nearest proposals. This is substantive disclosure not present in structured fields.

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 and scope are front-loaded in the first sentence, and the remaining sentences each carry distinct information (match mechanics, weak-fit caveat, no-fit fallback, sibling routing). It is dense but nearly every clause earns its place; slightly long for a single-parameter tool.

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 carries the return-value burden and does so: it explains what the best fits show (Foundation asks, grant appetite, declaring proposals) and the nearest-text proposals. Combined with the no-RFP fallback and sibling pointers, an agent has everything needed to call and interpret it.

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?

There is a single parameter with 100% schema description coverage, so the schema already documents it fully. The description restates the input as 'a project idea' but adds no format, length, or syntax guidance beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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 ('Given a project idea, find which Canton Dev Fund RFP(s) it fits') plus a secondary outcome (crowdedness). It explicitly names the siblings it is not (list_rfps, detect_builder_overlap), so an agent can distinguish it 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 routing: 'For the full RFP list use list_rfps; to include ecosystem projects as well as proposals use detect_builder_overlap.' It also handles the negative case ('If no RFP fits, the idea can still be filed as an individual initiative'), leaving nothing to inference.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: matching is a keyword heuristic over release bodies, so results are probable rather than authoritative and may miss rewording or false-positive on incidental mentions.

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?

Three short sentences, front-loaded with what the tool surfaces before moving to scope then mechanism. No filler, no repetition of the title, and the heuristic caveat arrives last where it belongs.

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 one-parameter, annotation-covered read tool with no output schema, the description supplies the essentials: subject matter, domain, and the matching mechanism. It leaves the agent guessing about result shape, ordering, and whether zero matches means "no security releases" or "keyword miss," which is a minor but real gap given there is no output schema to fall back on.

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?

The single `limit` parameter is fully described in the schema (max 30, min 1, default 10), so the schema does the heavy lifting. The description contributes nothing about the parameter, which is the correct baseline of 3 for near-total schema coverage.

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 ("Surface release notes") scoped to security/CVE fixes, with "Canton-specific" narrowing the domain. It never names a sibling such as search_release_notes, so an agent must infer the boundary between this narrow filter and the general release-note search on its own.

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?

Usage is implied by the security/CVE framing and the stated keyword heuristic, which tells the agent this is the targeted lookup rather than a broad search. However, there is no explicit when-to-use, no when-not-to-use, and no named alternative to route to when this heuristic surfaces nothing.

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 readOnlyHint, idempotentHint, and closed-world scope. The description adds a crucial behavioral constraint not in annotations: it searches only the live ecosystem directory (not proposals or other sources), and it is Canton-specific. No return-value details are given, but pagination is covered in the 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?

Front-loaded with the core purpose and scope, and the alternative is stated efficiently. The sentence is a bit dense with colons but every clause earns its place.

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 read-only similarity search with full schema coverage and annotations, the description provides all necessary context: what it does, what it searches, when to use it, and which sibling to use for a related task. No output schema exists, but pagination behavior is described in the schema for offset.

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%, so parameters are well documented. The description clarifies that 'description' is the free-text query and what fields are matched against, but adds nothing about limit/offset beyond what the schema already states.

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 ('Find'), resource ('Canton ecosystem projects'), and matching scope ('free-text description by matching across title + category + description + tags'). It also explicitly distinguishes itself from sibling detect_builder_overlap.

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 a clear when-to-use ('Useful before proposing a project to check overlap') and names the alternative for a related but different need ('to also check pending/past Dev Fund proposals... use detect_builder_overlap instead').

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 readOnly, idempotent, non-destructive and a closed world, so the safety profile is covered. The description adds useful scope context: the exact corpus searched, Canton-specificity, and that no CIP id lookup is performed. It stops short of describing result volume or how cross-source results are merged, which would be the remaining behavioral gap.

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 the core action and corpus, then routing rules. The long source enumeration and two worked examples add length, but each clause carries routing or scope information rather than filler.

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 still conveys corpus scope, cross-source nature, and the CIP-id boundary. What is missing is any indication of result shape or ranking across the many sources, which matters for a tool that fans out to a dozen corpora.

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%, so both parameters are already documented and the baseline is 3. The description goes slightly beyond by emphasizing the free-text nature of the query ('topic described in words', including nickname-style phrases), clarifying how to populate the required parameter. limit_per_source is not discussed, so it is not a full 5.

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 ('single free-text query across CCPEDIA's entire corpus') and enumerates the covered sources precisely. It also distinguishes itself from siblings by noting it does not require a CIP id and by naming get_cip_citations as the single-CIP alternative.

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?

Explicit when-to-use ('exhaustive cross-source roundup on a topic described in words'), when-not ('narrow single-source searches prefer the specialised tools'), and names the specific alternative with a triggering condition ('if the user already gives a specific CIP id/number, use get_cip_citations'). Nothing is left to inference.

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 readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is fully carried by structured data. The description adds only the return content ('ports, endpoints, services, links'), which is genuinely useful in the absence of an output schema but is not deep behavioral context. A 3 is appropriate given the annotations do the heavy lifting.

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?

Three short sentences, all front-loaded: purpose plus contents first, then scope exclusions, then the routing rule. Nothing is repeated and every clause carries new information.

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 single-enum lookup tool with annotations covering safety, the description supplies the two things not in structured data: the scope boundary and a sketch of the returned reference. Without an output schema, a slightly fuller picture of the returned shape would be ideal, but an agent has enough to call this 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 coverage is 100% and the single parameter's enum is self-documenting, which sets the baseline at 3. The description adds value by rendering the enum values as human-readable API names ('Token Standard APIs', 'Splice HTTP'), helping match those to how a user phrases the request. It stops short of clarifying ambiguous cases between similar APIs, so it is a modest gain, not a full one.

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 ('Get a structured reference') and enumerates exactly what the reference contains (ports, endpoints, services, links) and which seven APIs are covered. It explicitly rules out GitHub, REST, and non-Canton APIs, so an agent can separate it from the many doc-fetching siblings without opening the 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 when the user names one of these Canton APIs') and names the alternatives for the other case ('use search/semantic_search for broader doc lookups'). Negative scope is also stated ('Not for GitHub, REST, or non-Canton APIs'), so both the when and the when-not are covered.

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 readOnly/idempotent/non-destructive, so the bar is lower. The description still adds real value beyond them: it enumerates the returned fields and warns that TVL/volume/users may be null when only the Scan API source is available, which prevents an agent from treating nulls as an error.

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 the action and scope, then the return payload and the null caveat. No filler, though the return-field list could be tightened.

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 exists, so the explicit enumeration of returned fields plus the null-source caveat is exactly the compensation needed. What remains uncovered is minor: error behavior for an unknown or ambiguous prefix.

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% and the schema already documents both the contract-id meaning and prefix support. The description's '(contract id from the Scan API)' largely restates the schema, so it adds only marginal meaning.

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+resource ('Fetch metrics for one specific Featured App by its app_id') and scopes it to a single app, which distinguishes it from the plural listing tool. It does not name list_featured_apps as the sibling that produces those ids in the description itself, keeping it short of a 5.

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 phrase 'one specific Featured App' implies you need an app_id in hand, and the schema points to list_featured_apps for discovery. However, there is no explicit when-to-use/when-not or named alternative in the description, so usage is only implied.

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 cover read-only/idempotent/non-destructive, but the description adds substantive context the schema can't: provenance semantics (chain_derived for CC vs issuer_reported for everything else), the CIP-0056 reason those numbers aren't audited, and that holder counts appear as null rather than zero. This is exactly what an agent needs to avoid misusing the output.

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 the core purpose, then the caveats, then the scope limit. The provenance sentence is long but every clause earns its place given the unreliable-data warning it conveys; slightly dense but not padded.

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 carries the full return-shape burden and does so: it explains what each row contains (provenance), how holder counts surface (null, not zero), and where data originates (CCTools public API). Nothing an agent needs to interpret the response 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 coverage is 100% and already documents case-insensitivity and the omit-for-all behavior, so baseline is 3. The description adds value by enumerating the concrete valid asset set (CC, CBTC, HECTO, HANDL, USDCx, EDELx, cETH), which the schema only gestures at with two examples, reducing the chance of an invalid slug.

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 ('Get total token supply') and enumerates the exact asset universe (CC, CBTC, HECTO, HANDL, USDCx, EDELx, cETH). The scope clause 'Canton-only; cannot price or size-supply any other chain's tokens' cleanly separates it from siblings like get_token_market and get_network_stats.

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 clear operating context: omit the asset param to return all seven, and use it only for Canton-ecosystem assets. The exclusion ('cannot price or size-supply any other chain's tokens') is a useful when-not boundary, though it never names an alternative tool to use instead when the data isn't Canton-scoped.

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 cover the safe-read profile (readOnly, idempotent, closed-world), and the description adds real behavioral detail on top: articles, news, and press releases come back in full, while reprints and partner press are truncated to an excerpt with a link, and long posts are paginated via offset. It omits error behavior for an invalid id and whether offsets beyond the end are safe.

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 first clause is front-loaded with the core action, and every sentence carries information (fields, id provenance, excerpt policy, pagination). The phrasing is dense and slightly awkward ('by the id list_blog_posts or search gave'), but there is no filler.

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 3-parameter read tool with annotations and no output schema, the description covers what is returned, how truncation and excerpts work, and how to page. Only edge-case behavior (bad ids, offset past the end) is unstated, which is a minor gap.

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%, so the baseline is 3; the description earns a step up by explaining that some post kinds return only an excerpt, which is important context for interpreting chars and offset. The id and chars semantics themselves are left entirely to the schema.

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 gives a specific verb and resource ('Get one blog post'), states the return fields (title, kind, author, date, text), and explicitly ties the required id to sibling tools ('the id list_blog_posts or search gave'), which cleanly separates it from list_blog_posts and 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?

It tells the agent where ids come from (list_blog_posts or search) and when to use offset ('to keep reading a long post past the first part'). It does not explicitly say when not to use it (for example, 'do not use this to browse posts, use list_blog_posts'), so it stops short of a full routing rule.

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 readOnly=true, idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds real behavioral value by disclosing what the result is composed of (github_releases notes plus forum/GitHub reports near the release window), which tells the agent the output is an aggregated synthesis rather than a raw changelog. It stops short of mentioning any gaps in coverage or freshness limits of those sources.

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?

Three sentences, front-loaded with the core purpose, then the trigger, then a format hint. Every sentence carries information, though the trailing version-string sentence overlaps with what the schema already provides.

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 read-only, no-output-schema tool with fully documented params, the definition covers purpose, trigger, data sources, and input format. What is missing is minimal: no indication of result shape/size or how partial coverage is signaled, but an agent can call this correctly as written.

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% (all three params documented, including repo alias resolution and auto-inference), so the baseline is 3. The description's only added guidance is that version strings should match github_releases tags with or without a leading 'v', which largely restates the schema's own examples.

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?

Specific verb+resource+scope: compares two Canton/Daml/Splice SDK versions and returns the changes between them, aggregating release notes and community reports. It also stakes out a domain boundary ('Canton-specific'), which distinguishes it from generic siblings like search_release_notes or get_sdk_changelog.

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 condition: 'Use when a developer is planning an upgrade and asks what breaks moving from X to Y?' That is clear context and a concrete user intent. It does not, however, name alternatives or exclusions (e.g. vs get_sdk_changelog, check_deprecation, or find_security_patches), so routing between near-neighbors is still left to inference.

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 readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context — that the returned content is the proposal text only and does not reveal on-chain fate — but says nothing about truncation, size limits, or return shape for large bodies.

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 sentences, all front-loaded with the core purpose first, then sibling routing, then scope restriction. Every sentence carries routing or scope value, though the sibling enumeration is dense enough that it could be trimmed slightly.

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 exists, so the description carries the burden of describing the return, and it does: 'full markdown body', 'Returns only what the proposal SAYS'. Combined with complete sibling routing and scope exclusion, an agent has everything needed to call 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 coverage is 100% and the single 'id' parameter is already documented with the same example formats ("0001", "CIP-0042", "PR-0117"). The description repeats these examples but adds no syntax or resolution semantics beyond the schema, so 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 specific verb (Fetch), resource (full markdown body of a single CIP), and selector (by ID), with example ID formats. It also disambiguates scope explicitly with 'Returns only what the proposal SAYS', so an agent can distinguish it from siblings like get_cip_vote_outcome and get_cip_history 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?

Names three alternatives and the exact condition that selects each: get_cip_vote_outcome for on-chain fate, get_cip_history for the status timeline, list_cips for browsing/filtering multiple. It also excludes the wrong ecosystem ('Canton/Daml/Splice only, not Cardano'), leaving nothing to inference.

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 readOnlyHint, idempotentHint, non-destructive, closed-world, so the safety profile is covered. The description adds valuable behavioral context: the surprising case where old CIPs put the actual proposal text in attachments while get_cip only returns a header block, plus the exact return contents. It stops short of pagination/empty-result behavior, so not a full 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?

Front-loaded with the core action and return payload, then the routing and scope caveats. Dense and mostly waste-free, though the return-field enumeration and the disambiguation clauses make it a longish block rather than a tight one.

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 exists, but the description fully describes the returned fields, and annotations cover the safety/idempotency profile. It even pre-empts the confusing edge case where the attachment carries the real proposal text, so an agent has everything needed to call and interpret results 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 the single 'id' parameter is documented with format examples ("0001", "CIP-0042"), so the schema does the heavy lifting. The description adds no syntax or format detail beyond what the schema provides, making the baseline 3 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?

States a specific verb (get) and resource (file/PDF attachments of a single CIP), enumerates the returned fields (filename, page count, URL, extracted text), and explicitly distinguishes itself from siblings get_cip and get_cip_votes. An agent can tell exactly what it retrieves without opening the 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 routing: use get_cip for the index entry vs this tool for actual proposal text in older PDF-only CIPs, and use get_cip_votes for the who-voted-how breakdown. It also states scope boundaries ('Canton ecosystem only. Not Cardano or other CIP schemes'), which is a when-not rule.

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 readOnly/idempotent/non-destructive, and the description adds substantial beyond-schema context: per-source granularity (individual posts and messages, not just counts), full mailing-list scope with no exclusions, and the CCPEDIA-unique mailing_messages.cip_id join. It also discloses corpus scope (Canton/Daml/Splice only).

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 the core purpose and benefit, and the source enumeration is dense but useful. It runs long and has minor repetition of the CCPEDIA value proposition, but every sentence largely earns its place.

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 single-param, annotation-covered read tool with no output schema, the description fully conveys what is returned (per-source counts and samples) and where it draws from, leaving nothing an agent needs in order to call 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 coverage is 100% and the single cip_id param already documents accepted formats (padded/unpadded, PR-xxxx). The description adds little param-specific detail beyond the ecosystem/ID requirement, 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 specific verb+resource ('comprehensive citation graph for a CIP') and precisely enumerates what it covers across sources (sibling CIPs, forum posts, mailing-list messages, GitHub, blog, YouTube). It cleanly distinguishes itself from get_cip, get_cip_votes, and get_cip_mentions by naming their distinct scopes.

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?

Explicitly states when to use it ('who is referencing CIP-X and where', impact analysis, with a known CIP id), and routes to alternatives: get_cip for proposal text, get_cip_votes for votes, get_cip_mentions for legacy counts, full_context for free-text with no known id. Exclusions are clearly stated.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description still adds real value by scoping the return content (history only, no proposal body or vote tallies) and disambiguating the 'CIP' namespace. It stops short of describing pagination or ordering guarantees for the timeline.

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?

Three tight sentences: what it returns, when to use it, and what it is not — the routing exclusions are front-loaded rather than buried. No filler.

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?

Single required param, full schema coverage, no output schema — the description already conveys the return content (dated from->to transitions) and the scope boundaries, which is everything needed to call 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 coverage is 100% and the schema itself supplies ID format examples ("0001", "CIP-0042", "PR-0117"). The description adds nothing about the id parameter beyond what the schema already documents, so 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 specific verb and resource (status-transition timeline of a single CIP) and illustrates the output shape (Draft->Review->Final). It explicitly distinguishes itself from get_cip and get_cip_votes, so an agent can separate the three without opening schemas.

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 ('how/when did CIP-X move through governance' questions) and names the alternatives to use instead for other needs (get_cip for the body, get_cip_votes for tallies). Ecosystem scoping (Canton only, not Cardano) removes a realistic collision.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful non-annotation context by naming the three data sources it aggregates (dev-fund PRs, ecosystem projects, status transitions), which tells the agent what dimensions of 'tracking' come back. It does not mention freshness, rate limits, or behavior when no code links exist.

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?

Three compact sentences, front-loaded with the action and the payload, then the usage note. 'Canton governance.' is a fragment that adds domain scoping but is slightly terse; nothing is wasted overall.

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 carries the burden of saying what comes back, and it does list the three evidence categories. Combined with annotations covering the safety profile and a fully documented single parameter, an agent has enough to invoke and interpret it; only return-format details (e.g. links, counts, status vocabulary) are absent.

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?

There is a single required parameter with 100% schema description coverage, including accepted ID formats ('0112', 'CIP-0112', 'PR-0088'). The description adds nothing about the identifier beyond what the schema already documents, so 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?

The description states a specific verb and resource: report whether code/grants are tracking a given CIP, enumerating the evidence types (dev-fund PRs, ecosystem projects, status transitions). That is far more than a restatement of the name. It stops short of explicitly differentiating itself from near-neighbors like get_cip_history or get_cip, leaving that inference to the agent.

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 sequencing advice: 'Use after find_cip_for_feature to gauge readiness,' which tells the agent both the preceding call and the decision context. There is no statement of when not to use it or which sibling to prefer for adjacent questions, so it falls short of a full 5.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value beyond them: it discloses output granularity ('aggregated per-source counts, not individual items') and scope boundaries ('Canton ecosystem only. Not Cardano or other CIP schemes').

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?

Dense but front-loaded: the core verb and source list come first, followed by the use case, output granularity, and sibling routing. Every sentence carries routing or behavioral information, though the multi-clause sentences are slightly heavy.

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 still explains what comes back ('aggregated per-source counts'), the scope, and the exact alternatives for adjacent needs. Nothing an agent needs to select and invoke this 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?

Only one parameter with 100% schema coverage, so the schema already documents the id format ('0001', 'CIP-0042', 'PR-0117'). The description refers to 'a given CIP'/'CIP-X' but adds no format or syntax detail beyond the schema, so 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 specific verb+resource (reverse-reference/backlink lookup of CIP mentions) and enumerates the source types covered. It explicitly names the sibling it is not (get_cip_citations, get_cip, get_cip_votes), so an agent can distinguish it 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 an explicit use trigger ('who is discussing CIP-X and where' / impact questions) and names alternatives with the exact condition that selects them (individual posts/messages → get_cip_citations; proposal text → get_cip; votes → get_cip_votes). No inference required.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the data source is the ledger rather than discussion threads, and it returns the full set of citing vote requests with dates. It stops short of noting auth needs or result-size behavior beyond what the schema states.

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 purpose and return value are front-loaded, and every sentence carries routing value (distinction, example, scope). The CIP-0116 illustration is longer than strictly necessary but does help an agent recognize the data pattern being queried.

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 does the work of describing the return contents (vote requests, outcomes, dates) and the scope limitation. It could say slightly more about the response shape or result size, but it is sufficient for an agent to call this 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 both parameters (cip_id, limit) are documented in the schema itself, including accepted id formats and pagination bounds. The description adds no parameter-level detail beyond what the schema already provides, 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 ('Find out whether a CIP was actually acted on ON CHAIN') and names what is returned (DSO governance vote requests citing the CIP, with outcomes and dates). It explicitly distinguishes itself from the closest sibling, get_cip_votes, and scopes itself to the Canton ecosystem.

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?

Explicitly frames the when-to-use question ('was it decided') and contrasts the alternative: get_cip_votes reads the cip-vote mailing list, this reads the ledger. It also states an exclusion boundary (Canton only, not Cardano or other CIP schemes), so routing is unambiguous.

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 establish read-only, idempotent, closed-world safety, but the description adds real behavioral context: messages are returned oldest-first, the content is raw as-sent text where each SV states its vote in the body, and the first message is typically an announcement rather than a vote. This prevents misreading the payload as a tally. It does not discuss paging output details, but the schema covers those.

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 the core action and content definition, then disambiguation. Information-dense with no filler, though the parenthetical asides and the trailing 'Canton only / not Cardano' sentences make it denser than strictly needed for a single-purpose read tool.

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 a read-only tool with full schema coverage, existing annotations, and no output schema, the description supplies everything an agent needs: what is returned, ordering, interpretation caveats, sibling routing, and scope boundaries. Nothing material 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 coverage is 100%, and every parameter (cip_id, limit, offset) is documented in the schema including formats, defaults, and the header/count behavior. The description adds only the 'oldest first' ordering hint, which is marginal beyond what the schema already provides, 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 specific verb+resource ('Get the cip-vote mailing-list messages for a specific CIP') and immediately defines the scope: raw message thread, oldest first, NOT a computed count. It explicitly names the sibling it is not (get_cip_vote_outcome) 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?

Explicit when-to-use (reading who said what on Governance-type CIPs) and when-not (on-chain tally, attachment PDFs, status timeline), each routed to a named alternative. It even scopes the ecosystem ('Canton only, not Cardano'), removing ambiguity from the overloaded 'CIP' term.

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 cover readOnly/idempotent/destructive/openWorld, so the safety profile is handled. The description adds genuinely useful behavior beyond that: it discloses the derivation (two CCPEDIA-only joins, latest stable tag per repo + validator-announce list) and a freshness guarantee versus the Foundation KB snapshot that can lag weeks. It does not describe pagination or response shape, but no output schema exists and the tool is parameterless, so the gap is minor.

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 purpose is front-loaded and every sentence carries weight (scope, derivation, freshness, usage, alternative). It is slightly verbose with emphatic phrasing ('ALL AT ONCE') and stacked example questions, but nothing is filler and the structure routes the agent efficiently.

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 parameterless, read-only, idempotent tool with no output schema, the description supplies everything needed to select and call it: covered resources, data provenance, freshness characteristics, and the competing sibling. Nothing material 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The description does not introduce any parameter semantics, which is appropriate given the empty schema.

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 set (Canton SDK, Splice, Daml, DPM versions plus per-network deployment status and upgrade windows) and clearly distinguishes itself from siblings like get_latest_release and get_sdk_changelog. An agent can tell exactly what this returns 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 triggering questions ('what version should I target?', 'is Splice X.Y.Z still current?', 'what is on MainNet?'), a scope condition (MULTIPLE packages), and a named exclusion routing to get_latest_release for single-package release notes. This is textbook when/when-not/alternative guidance.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation context: source attribution (CCTools public API), a Canton-only scope constraint, and a data-freshness warning about Cantex. It stops short of describing return format or pagination, but with no output schema that gap is minor.

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 the core purpose and fields, then the disambiguation. The Cantex parenthetical is a touch wordy and slightly interrupts the routing sentence, but every clause carries real information (coverage gap, staleness reason). No filler.

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 read-only, no-output-schema pool query the description covers purpose, fields returned, source, scope, coverage caveat, and the alternative tool. Without an output schema, more detail on the response shape would help, but the field enumeration partially compensates. Nothing essential to correct invocation 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 enum parameter is fully documented ('Restrict to one DEX. Omit for all three.'). The description's listing of OneSwap, Send, and Tradecraft mirrors the enum values without adding syntax or default behavior beyond what the schema already states, 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?

Specific verb+resource ('Get per-pool DeFi liquidity data') with named fields (pair, TVL, fee rate, APY, reserves), named sources (OneSwap, Send, Tradecraft), and explicit sibling differentiation from get_token_market (pool-level vs aggregate protocol-level). An agent can distinguish this from get_token_market 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?

Explicitly routes the agent: use this for pool-level detail, use get_token_market for aggregate protocol-level TVL. It even explains why the alternative differs (Cantex coverage) and flags a caveat (Cantex API down, numbers marked stale). When-to-use and when-to-use-the-other are both stated.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior beyond that: newest-first ordering, snippet-bearing comments/reviews, and the concrete event types that appear when include_events is on. It stops short of describing result shape or volume limits, which matters given 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?

Content is front-loaded: the payload is stated before the example queries. The example-question list is slightly redundant with the opening clause, but each sentence still carries routing value.

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 does the necessary work of explaining what comes back (comments/reviews with snippets, event types, newest-first). Paging and lookback windows are left to the schema, which documents them adequately. A note on result volume or empty-window behavior would complete it.

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 days/limit/offset/include_events are already documented with defaults and bounds. The description reinforces include_events ('optionally... timeline events such as labels added, reviewers requested...') but largely restates the schema, and says nothing about days/limit/offset. 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?

The description names a specific verb+resource (activity in the Canton Dev Fund) and enumerates the payload precisely: comments and reviews with snippets, plus optional timeline events. It is clearly distinguishable from data-shaped siblings like get_dev_fund_lifecycle or get_dev_fund_person, though it never names an alternative explicitly.

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?

Three concrete example user questions ('what is going on in the Dev Fund', 'what did the committee say this week', 'which proposals just got reviewed') give an agent a clear trigger set. There is no explicit when-not guidance or named alternative 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.

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

Annotations already establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description's job is to add context — and it does: percentiles are linear interpolation, open proposals are never mixed into completed-stay statistics, every figure carries its n, and the board history has known gaps that are stated in the answer. These methodological caveats are exactly the kind of trust-relevant detail an agent cannot get from annotations.

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 and reasonably tight for the amount of information packed in, but it is delivered as three very long, comma-chained sentences where the overview metrics, the number mode and the flow view blur together. A reader must re-parse to separate the modes, so structure is adequate rather than efficient.

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?

There is no output schema, so the description carries the burden of describing returns — and it does, covering the overview funnel statistics, the single-proposal history, and the flow view separately, plus caveats about n, gaps and interpolation. Given the tool's analytical complexity, this is close to complete, with only sibling routing left uncovered.

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%, so the baseline is 3, but the description genuinely enriches both parameters beyond the schema: for number it enumerates the returned history (every column stay with date and mover, waiting state with reason, first response, votes, steps back), and for view "flow" it lists the weekly open/voting/approved/closed counts and backlog. That is meaning the schema's one-line parameter descriptions do not convey.

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: it derives the Canton Dev Fund proposal lifecycle from board column history, with a concrete metric inventory (funnel counts, median/p90 days per column, time to decision, time to first human response, waiting states, bot labels, steps back). The scope is unmistakable and analytically distinct from sibling tools like get_dev_fund_activity or list_stuck_proposals, but it never names those alternatives, so sibling differentiation is left implicit.

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 does tell the agent how to use the two modes ("Pass number for one proposal", "Pass view 'flow' for the weekly ... counts"), which is real invocation guidance. However, it gives no explicit when-to-use/when-not-to-use versus the many adjacent dev-fund and proposal siblings, so routing guidance is implied rather than stated.

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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without description help. The description adds the content scope of the lookup but says nothing about auth requirements, rate limits, or what happens if the login is unknown; with annotations carrying safety, this is adequate but not rich.

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 core identity ('Who is this person... by GitHub login') is front-loaded, and the following enumeration of returned fields plus the usage sentence are all informative rather than filler. The middle sentence is a dense run-on list, which costs a little readability, but nothing is wasted.

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?

There is no output schema, so the description carries the burden of conveying return contents — and it does so thoroughly by enumerating the facets. Combined with the stated use case and the annotation-covered safety profile, an agent has enough to call it correctly; only lookup-failure and auth behavior remain unaddressed.

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% — the login parameter is documented in the schema with format constraints and examples. The description only restates 'by GitHub login' and adds no format, case-sensitivity, or lookup-failure semantics, so baseline 3 is correct.

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 ('who is this person in the Canton Dev Fund, by GitHub login') and enumerates the distinct data facets returned: SIG memberships, authored proposals, review/comment activity, review requests, assignments, and champion lines. That granularity clearly distinguishes it from siblings like search_dev_fund, get_dev_fund_activity, and find_expert.

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 an explicit use case: 'Use to judge who a possible champion or reviewer is and how responsive they are.' That tells the agent when this tool is relevant, but it names no alternatives (e.g. find_expert or list_proposals_needing_champion) or explicit exclusion conditions, so it falls short of a full 5.

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 readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely new traits: results come from CCPEDIA's cached forum index (staleness implication), it is Canton-only, and only the first ~15 posts are returned. Pagination or a way to fetch further posts is not disclosed, which keeps this from a 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?

Purpose and returned fields are front-loaded ahead of the sibling routing and id-sourcing hints, so the shape is good. The parenthetical '(Discourse at forum-style discussions on ccpedia.xyz)' is garbled and mildly redundant with the opening clause, costing a point.

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 carries the burden and does enumerate the return fields and the ~15-post truncation and cache caveat. It omits how to retrieve posts beyond the first ~15 or whether the cached index lags live forum state, so it is strong but not fully 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% and the single parameter already documents accepted forms (3242 or "topic:3242") and excludes doc-page ids. The description only lightly reinforces the id's origin ('search results or trending'), which the schema largely covers, 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 (get) and resource (a single forum thread) plus the exact source (Canton community forum, CCPEDIA cached index) and the fields returned (title, category, view/post counts, first ~15 posts). It is clearly distinguishable from sibling readers like get_github_discussion and get_mailing_thread.

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?

Explicitly routes among alternatives: 'For GitHub Discussions use get_github_discussion, for sync.global mailing-list threads use get_mailing_thread.' It also tells the agent where to obtain the required id ('from search results or trending'), leaving nothing to inference.

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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by explaining that it returns the complete untruncated text versus a search snippet, and that an id is mandatory. It does not mention behavior on an invalid or stale id, which keeps it below a 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 tight sentences, front-loaded with the verb and resource, then the precondition, then the exclusion. Nothing is redundant, and the most decision-relevant constraint (use after search) appears early.

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 one required parameter, rich annotations, and no output schema, the description covers what an agent needs: what is returned (full text), the domain scope, and the prerequisite. It omits only edge behavior such as errors for invalid ids or size limits on large pages.

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 schema itself documents both accepted forms (3242 or "doc:3242") and the forum-id exclusion. The description's 'Requires an id' and 'numeric id' add little, and 'numeric' slightly understates the string form the schema permits. 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?

States a specific verb and resource: fetch the FULL text of one indexed Canton-ecosystem documentation page by numeric id. It explicitly scopes the content domain (Canton/Daml/Splice and partner docs), which lets an agent separate it from get_discussion, get_api_reference, and the search tools.

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 ordering rule: use AFTER search or semantic_search returns a doc id. It also states the negative case ('Not a discovery tool; use search/semantic_search first'), and the schema reinforces routing by noting forum topic ids belong to get_discussion.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description's real added value is defining what counts as a 'gap' (zero replies, no label assigned) and the Canton-specific scoping, but it says nothing about ordering, recency windows, or how the three categories are combined in the response.

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?

Three tight sentences: the gap taxonomy first, scope next, the alternative last. No filler and nothing redundant with the annotations.

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 does the work of telling the agent what the result represents, and it does so for all three gap types. Minor gaps remain around result ordering and whether categories are merged or separated.

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?

One parameter with 100% schema description coverage, so the schema already documents limit, its 1-20 range and default. The description's phrase 'max rows per gap type' restates the schema rather than adding interpretation, which is the baseline case.

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?

Specific verb ('surface') plus a precisely enumerated resource: unanswered high-view forum threads, unreplied mailing threads, and unlabeled Dev Fund proposals. The three gap categories are defined inline, so an agent knows exactly what comes back without opening the 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?

Explicitly routes a competing question away with 'For per-category funding levels use get_funding_landscape,' and gives a use framing ('where the ecosystem needs help'). It does not state a when-not condition or name the sibling list_proposals_needing_champion, which overlaps the Dev Fund gap category.

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 readOnly/idempotent/non-destructive/closed-world, so the safety bar is pre-covered. The description adds genuinely useful behavior beyond that: it returns the 3 NEAREST entries which may not exactly match, a near-miss caveat that changes how an agent should trust the result.

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 and scope are front-loaded, and the routing sentences carry real decision value rather than filler. It is dense and long for a single-parameter lookup tool, but each sentence (scope, return caveat, exclusions, alternatives) earns its place.

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 exists, and the description compensates by explaining the return shape (3 nearest entries) and its reliability limits. Combined with the exclusions and alternatives, an agent has everything needed to call this 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?

Only one parameter, and schema coverage is 100% with the schema itself supplying example question strings. The description adds no syntax or format detail beyond the schema, so 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 specific verb+resource (look up answers in the Canton Network developer FAQ) and enumerates the exact topic domains it covers. It distinguishes itself from siblings by explicitly naming semantic_search, get_doc, get_started_guide, and get_api_reference as separate routes.

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?

Explicit when-to-use ('Canton-specific' questions), when-not ('do NOT use for other blockchains or general/non-Canton questions'), and alternatives with the selecting condition ('if none of the 3 directly answers... use semantic_search... then get_doc'). Routing to get_started_guide and get_api_reference is also stated.

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 readOnlyHint=true, idempotentHint=true and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: results are matched-page snippets from a site index rather than curated content, and the scope is restricted to canton.foundation. Return shape is mentioned but not pagination or depth behavior.

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?

Three dense sentences, front-loaded with the resource and source, then constraints, then usage. Every sentence carries information, though the topic enumeration is somewhat redundant with the schema examples and could be trimmed.

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 usefully clarifies that results are snippets (not full pages) and scoped to Canton. An agent has enough to call it correctly, though result size, ranking behavior, and snippet granularity are left unstated.

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 schema already lists example topic values ('team', 'working groups', 'membership', 'grants', 'board') matching those in the description. The description thus largely restates the schema's guidance rather than adding syntax, formatting, or matching semantics; baseline 3 is correct.

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?

Specifies a concrete verb and resource ('Retrieve official Canton Foundation pages (canton.foundation)') and enumerates the content types covered: team/board bios, working groups, membership process, grants program. It also explicitly separates itself from the curated knowledge base, so an agent can distinguish it from search/semantic_search siblings.

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 a clear trigger condition: 'Use when a user asks about Foundation people, governance structure, or member/grant processes.' It also carves out the negative case by noting results are Canton-only and come from the site index rather than the curated KB. It stops short of naming a specific alternative tool, so it falls just under 5.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is low. The description still adds real context by characterizing this as an aggregate overview rather than a raw listing, and by scoping it to Canton specifically, which helps set expectations about the response.

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?

Three short sentences, front-loaded with what the tool returns, followed by scope and usage. Every sentence carries information and nothing is padded.

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 does the work of describing the return content (counts, top categories, recent activity), and annotations handle the safety profile. The only gap is freshness or granularity of "recent activity," which is minor for a single-parameter read tool.

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 only one optional parameter, so the schema already documents the category filter with examples. The description reinforces the filter's purpose (judging a category's funding level) but adds no syntax or format detail beyond the schema.

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 names the resource (Canton Dev Fund) and enumerates the shape of the output: proposal counts by state and label, top categories, recent activity. This distinguishes it from narrower siblings like get_dev_fund_activity or get_dev_fund_lifecycle, though it never names an alternative explicitly.

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?

"Use to gauge whether a category is over- or under-funded before proposing" gives a clear decision context and ties the tool to a workflow stage. It stops short of naming when NOT to use it or which sibling to prefer for raw proposal lists, so it is clear context without 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: results come from CCPEDIA's cache rather than the live GitHub API, and coverage is restricted to Canton Network/Digital Asset repos. It does not mention cache staleness or comment pagination limits, which keeps it below a 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?

Three sentences, front-loaded with the action and resource, then scope, then disambiguation. Every clause carries distinct information (source of id, cache vs live, sibling routing) with no repetition of the schema or annotations.

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?

There is no output schema, so the description correctly takes on the return contract by stating it returns the full body and comments. Combined with the cache-vs-live note and Canton-only scope, an agent has what it needs to call it; the only unaddressed item is whether long comment threads are truncated or paginated.

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 parameter is documented with a concrete node-id example, so the schema carries the syntax burden. The description still adds provenance the schema lacks: the id is a GitHub GraphQL node id obtained from list_github_discussions, which tells the agent not to invent or reuse an internal discussion id.

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+resource ('Get the full body and comments of a single GitHub Discussion') plus the scope (Canton Network or Digital Asset repos, by GraphQL node id). It explicitly distinguishes itself from the two nearest siblings, get_discussion (Canton web forum) and get_mailing_thread, so an agent can disambiguate 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?

Tells the agent where the required id comes from ('from list_github_discussions') and which tools are the wrong choice for this data ('distinct from the Canton web forum (get_discussion) and mailing lists (get_mailing_thread)'). The 'CANTON-ONLY, read from CCPEDIA's cache. Not the live GitHub API' clause gives the condition under which this source is appropriate.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description goes further by disclosing the richness of the payload — individual SV votes with their own written reasons and who abstained — which tells the agent this is a heavyweight single-record fetch, not a summary.

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, zero filler. The identity of the resource is front-loaded, the returned contents are packed into one enumerative clause, and the usage/scope caveat comes last where it belongs.

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?

There is no output schema, so the description carries the burden of describing the return value — and it does so thoroughly, listing each field category an agent would need. Combined with annotations covering safety, nothing needed to 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 parameter already documents that a unique prefix is acceptable and that the value comes from list_governance_votes. The description adds no parameter-level meaning beyond that, 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 ('Get') and resource ('one Canton on-chain DSO governance vote request') and then enumerates exactly what is returned: proposed action, requester reason, per-SV votes with reasons, abstentions, outcome, effective date. That level of specificity separates it cleanly from siblings like list_governance_votes, get_cip_vote_outcome, and compare_governance_outcomes.

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?

Explicitly positions the tool in a workflow ('Use after list_governance_votes when a specific decision matters') and constrains scope ('Canton ecosystem only'). It doesn't name an exclusion case or a competing alternative for aggregate comparison (e.g., compare_governance_outcomes), so it falls just 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.

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds the meaningful constraint that only Canton/Daml/Splice repos are in scope, but says nothing about auth needs, error behavior, or what the lookup returns.

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 short sentences, zero filler, with the core action front-loaded and the scope restriction second. Nothing could be cut without losing information.

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 tool with no output schema, the description never indicates what is returned (status only, or full issue/PR payload), despite the name implying 'status'. Annotations and schema cover input safety and parameters, but the return-shape ambiguity is a real gap.

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%, with both params documented (repo with shorthand form, number). The description only restates 'repo + number' and adds no format or semantics 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 specific verb (look up) and resource (one GitHub issue or PR) with the lookup key (repo + number), which distinguishes it from the bulk sibling search_github_issues. It doesn't name that sibling explicitly, so it stops short of full differentiation.

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 scope constraint 'Canton/Daml/Splice repos only' implicitly tells the agent when this tool applies, but there is no explicit when/when-not guidance or pointer to search_github_issues for broader lookups. Usage must be inferred from the constraint.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real value beyond them: it discloses the exact return shape (category, key, KB value, live value derived right now, drift age in days, severity info|warn|stale) and the provenance of both sides of the comparison. It does not mention refresh cost or auth, but nothing critical is missing.

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-loads the core purpose and return fields, then the usage trigger, then ecosystem scope. Sentences earn their place, though the 'no other Canton MCP server exposes this kind of cross-source quality audit' line leans promotional rather than operational.

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 compensates by enumerating the returned fields and their semantics, and it explains the drift concept and data sources. An agent has enough to call it correctly; only minor details (pagination, ordering) are absent.

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 refresh parameter is fully documented in the schema (including the stored-vs-live evaluation semantics). The description adds nothing about the parameter, 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 specific verb (report where ... diverges) with two concrete resources (the Foundation Build-on-Canton KB snapshot vs CCPEDIA live signals) and names the underlying data tables (github_releases, network_state). An agent can tell this apart from detect_drift, outdated_guidance_detector, and check_deprecation because the description pins the comparison to the KB snapshot vs live signals.

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 when a user or another agent quotes a Canton SDK/Splice/DPM/Daml version from foundation_kb and you need to confirm it is current. It also scopes the ecosystem (Canton/Daml/Splice only). It stops short of naming the sibling alternatives (e.g., detect_drift) and when NOT to use this one.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond them by promising the specific payload shape (tag, date, release-notes URL) and flagging Canton-specific scope. It does not say what happens for an unknown or non-Canton package name, which is a real gap given the schema also accepts arbitrary 'owner/repo' values.

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 lead sentence states what is returned and for whom, then the Canton-specific constraint, then the usage rule — well front-loaded. It is dense and slightly overpacked for a one-parameter read tool, but every clause carries information.

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 compensates by naming the three returned fields, and it covers the required input and the routing decision against the sibling. An agent has everything needed to select and call it.

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 parameter already documents the same four names plus the owner/repo form. The description restates the package set, adding only the framing that it must be 'ONE NAMED' package. Baseline 3 applies since the schema carries the parameter detail.

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 ('Get the single latest release') and enumerates the returned fields (version tag, publish date, release-notes link). It scopes the tool to one named Canton-ecosystem package, which is enough to distinguish it from the broader version tools in the sibling list.

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 use condition with quoted example utterances ('what's the latest daml release', 'latest canton version') and names the alternative, get_current_versions, with the exact condition that selects it (cross-package snapshot or MainNet/TestNet status). Nothing is left to inference.

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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value beyond that: deterministic oldest-first ordering and the Canton-only/lists.sync.global scope restriction. It does not discuss paging behavior, but that is documented in the schema instead.

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 with no waste; the scope/ordering constraint is front-loaded and the routing exclusions come last. Nothing is repeated or padded.

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 read-only list tool with a fully documented 3-parameter schema and no output schema, the description covers what it returns (all messages, oldest first), the source channel, and the id source. 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 coverage is 100% and the id parameter documentation already explains both accepted id forms in depth, so the schema carries the load. The description adds only the provenance hint that the id comes from list_mailing_threads; limit/offset get no description-level elaboration. 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?

States a specific verb and resource ("Get every message ... in a specific Canton Network governance mailing-list thread on lists.sync.global"), names the concrete channel (cip-discuss, cip-vote, grants-discuss) and explicitly excludes the web forum and GitHub Discussions siblings. An agent can distinguish it from get_discussion / get_github_discussion 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 the prerequisite for the id ("Pass the thread id from list_mailing_threads") and names both alternatives it is not ("Not the web forum (get_discussion) or GitHub Discussions"). Both the when and the when-not are stated explicitly.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: source endpoint, 'Canton-only, cached snapshot (captured_at)', and the flagging behavior when upstream stops publishing rewards. Return format detail is limited but the caching semantics are a real addition.

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 the verb and source, then the field list. The enumeration of covered fields is long but each item earns its place given there is no output schema to fall back on. No filler sentences.

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 has to describe what comes back, and it does so thoroughly: SV list/count, voting threshold, sequencer count, latest mining round, featured-apps count, rewards in CC with closed round and date, plus caveats about stopped publishing and caching. Nothing an agent needs to call it 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?

Zero parameters, so the schema has nothing to document and the description carries no burden here; baseline 4 applies. The description does not need to explain parameter usage because no parameters exist.

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+resource ('Get the latest Canton Network ON-CHAIN state snapshot from the public Scan API'), enumerates the exact contents it returns, and names two siblings it is not. An agent can distinguish it from get_network_stats and get_token_market 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 exclusions with named alternatives ('NOT CCPEDIA content counts (get_network_stats) and NOT price/TVL (get_token_market)') and frames the use case as 'live network telemetry.' The positive trigger is implied rather than stated, so a 4 rather than a full 5.

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 readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered. The description adds genuinely new behavioral context by clarifying that the data is CCPEDIA's static content-catalog inventory rather than a live on-chain feed. It does not describe response shape or pagination, but with annotations doing the heavy lifting and no output schema this is a minor gap.

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?

Three sentences, front-loaded with the core purpose, then the enumerated inventory categories, then the negative scope and routing. No wasted text; each clause earns its place.

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 zero-parameter, read-only tool with no output schema, the description supplies the missing return-value context by enumerating the counted categories (CIPs, forum topics/posts, GitHub issues/PRs, dev-fund proposals, docs, videos, blog posts, mailing threads, radar items) and rules out on-chain interpretation. An agent has everything needed to select and call it.

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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly does not invent parameter guidance and instead spends its budget on output-category scope.

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 ('Get CCPEDIA's CONTENT-CATALOG metrics') and immediately scopes it to indexed inventory rather than live chain data. It explicitly names the sibling tools it is not (get_network_state, get_token_market), so an agent can distinguish it 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 when-to-use and when-not-to-use guidance, including the exact conditions that route to alternatives: 'For on-chain validators/rounds use get_network_state, for price/TVL use get_token_market.' Nothing is left to inference.

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 readOnlyHint, idempotentHint, non-open-world and non-destructive, so the safety profile is covered. The description adds that it operates on the npm registry index and is Canton-specific, useful context, but nothing about result ordering or response behavior beyond what the schema states.

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?

A single front-loaded sentence with the core verb and resource first and the scoping parenthetical after. Nothing is wasteful, though the parenthetical is slightly terse for an unfamiliar reader.

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 read-only list tool with complete schema coverage and annotation-declared safety, the description covers purpose, scope, and filterability. Return values are not described, but there is no output schema and pagination behavior lives in the schema, so little 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%, so the schema already documents limit, query, and offset (including paging semantics and full count echo). The description only restates that filtering by name is optional, adding no syntax or format detail beyond the schema.

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 (List) and resource (indexed Canton/Daml npm packages) with a scoping qualifier (sdk_versions registry=npm) and 'Canton-specific'. This distinguishes it reasonably well from generic version/repo tools, though it doesn't name a sibling explicitly.

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 says the list can be 'optionally filtered by name' but gives no guidance on when to use this tool versus alternatives like get_current_versions or list_repos. Usage is only inferable from the tool name and scope.

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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value by disclosing the breadth of returned content (parsed file facts, champion evidence, reviewers, statistics, event timeline) and the 'ONE proposal' scoping constraint. It stops short of return-format or pagination specifics, 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?

Front-loaded with the core purpose and the scoping phrase 'ONE ... proposal' before the long enumeration. The enumeration is dense but every clause maps to real returned data; the structure is efficient if slightly run-on.

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 carries the burden of describing return contents, and it does so comprehensively (state/board column, labels, parsed proposal facts, champion evidence, reviewers, discussion stats, event timeline). An agent knows exactly what it will get and when the result is or isn't the right source.

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?

With 100% schema coverage on a single parameter, the schema already documents 'number' as a PR/issue number with bounds and an example. The description only reinforces that the number comes from a prior list/search call, adding minimal syntax beyond the schema. 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 specific verb and resource ('everything CCPEDIA holds about ONE Canton Dev Fund proposal... by its PR number') and enumerates the payload domains it returns. This clearly distinguishes it from siblings like get_proposal_discussion and get_proposal_file, which target subsets of the same entity.

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?

Explicitly states when to use it ('after get_proposals, list_proposals_needing_champion or search_dev_fund returned a number') and names two alternatives with their distinct purposes (full conversation vs. full proposal text). The routing decision is fully deterministic.

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 cover the safety profile (readOnly, idempotent, closed-world), so the description's added value is ordering ('oldest first'), pagination via offset, the fact that the response states the full count, and the GitHub-role enrichment. That is meaningful context beyond the annotations, though response shape and error behavior are not described.

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 the core resource and its contents, followed by pagination and usage sentences. Dense but efficient; the trailing 'Canton-specific.' adds little beyond what the name already implies.

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 read-only, paginated discussion fetcher with no output schema, the description covers contents, fields returned, ordering, pagination, and purpose. An agent has everything needed to call 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 coverage is 100%, so kind, limit, number, and offset are all documented in the schema. The description only adds 'Pages with offset,' matching what the schema already says; 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?

States a specific verb and resource ('The conversation on ONE Canton Dev Fund proposal') and enumerates exactly what it contains: comments, formal reviews with verdicts, and inline review comments, each with author, GitHub role, date, and text. The 'ONE proposal' scoping and canton-dev-fund specificity separate it from generic siblings like get_discussion or get_github_discussion.

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 a clear use case: 'Use to read what reviewers, champions and the committee actually said, or why a proposal stalled.' That tells the agent when this is the right tool, but it does not explicitly name alternatives (e.g., get_proposal for metadata, get_proposal_milestones) or state when not to use it.

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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine value beyond them by asserting the content is returned 'exactly as in the PR head,' signaling verbatim, untransformed output. It does not cover size limits or truncation for large files, which keeps it from a 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?

Three tightly packed sentences with no filler: the first gives scope and file patterns, the second gives multi-file routing, the third gives usage sequencing. Front-loaded with the core 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?

With no output schema, the description carries the burden of explaining what is returned, and it does so by enumerating the substantive sections (abstract, specification, milestones, acceptance criteria, funding). Nothing about permissions or error cases is covered, but for a read-only extraction tool this is close to sufficient.

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 both parameters are already documented in the schema, and the standard baseline is 3. The description's note that a PR may add several files and that path selects one adds mild routing context but no syntax or format detail beyond the schema.

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+resource ('full text of the proposal file(s) a Canton Dev Fund PR adds') and identifies the exact file patterns (proposals/*.md, rfps/<category>/*.md). It is immediately distinguishable from get_proposal, which it names as the prerequisite sibling.

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?

Explicitly says 'Use after get_proposal when the details matter,' giving both the sequencing condition and the alternative to use when details don't matter. It also clarifies the multi-file case with the routing rule for the path parameter.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds meaningful behavioral context beyond them: the matching rule (issues whose body or title references the PR number), which tells the agent exactly how results are derived and why an issue appears.

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 tight sentences with the subject and scope front-loaded and no filler; the matching criterion is packed into a parenthetical rather than a separate 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 single-param, read-only lookup with no output schema, the description is nearly complete: it conveys scope, matching logic, and the return shape ('list ... issues'). Only minor gaps remain, such as whether an empty result is possible and what fields each issue carries.

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% and the single pr_number parameter is already documented with its repo context. The description only restates that it's one Canton Dev Fund proposal PR, adding location context but no format or edge-case semantics beyond the schema. 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 specific verb (list) and resource (related milestone tracking issues) scoped to one Canton Dev Fund proposal PR, which is far more precise than generic siblings like get_issue_status or search_github_issues. It doesn't explicitly name an alternative sibling, so it falls short of a 5.

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 'For one Canton Dev Fund proposal PR' framing implies the use case, but it never says when to prefer this over search_github_issues or get_issue_status, nor any exclusions. Usage is implied rather than stated.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond that: it discloses the return shape (number, title, state, author, board status, comment count), warns 'it is only an index,' and notes the response reports the full count. It doesn't discuss rate limits or error behavior, but that is a minor gap.

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 the core purpose, then scope boundaries and return shape. Every sentence carries routing or scoping information, though it is denser than strictly necessary and repeats the state filter that the schema already documents.

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 carries the burden of describing the return (an index of number/title/state/author/board status/comment count) and does so. It also covers filtering, pagination count reporting, ecosystem scope, and sibling routing — nothing an agent needs to call this 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%, so limit, state, and offset are already fully documented, including defaults and the max of 50. The description restates the state filter (open/closed/all) without adding syntax or behavioral nuance beyond the schema, so the baseline of 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?

States a specific verb+resource: 'List Canton Network Dev Fund grant proposals: community funding requests tracked on GitHub.' It explicitly distinguishes itself from the similarly named CIP tools (list_cips / get_cip) and from get_proposal, so an agent can disambiguate 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 an explicit use case ('what grants/funding requests exist' questions), names the excluded alternative (CIPs are governance specs handled by list_cips/get_cip), routes detail-seekers to get_proposal and get_proposal_discussion, and bounds scope with 'Canton ecosystem only.' When-to-use, when-not, and alternatives are all present.

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 establish readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior the annotations cannot: the feed is curated, live, time-sensitive, and each entry carries a deadline, affected components and a source link. It does not discuss freshness/caching or rate limits, but adds real value on top of the structured hints.

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 what the tool is, then content shape, then filter, then scope, then trigger. Three sentences, no filler, no repetition of schema detail.

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 zero required params and no output schema, the description carries the return-shape burden and does so by naming deadline, affected components and source link, plus the level filter. Minor gap: it never distinguishes the radar entry from sibling feeds like get_breaking_changes or get_upcoming_deadlines, which is the one thing an agent would still need to choose 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 coverage is 100% and each parameter already carries a detailed description, including the nuanced severity-floor semantics of 'level'. The description only repeats the level enum; it says nothing about limit or offset paging that the schema does not already state. 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?

States a specific verb and resource (get the Canton Network Radar) and enumerates the content precisely: breaking changes, upgrade deadlines, protocol migrations, validator actions, each with deadline/components/source. The scope constraint 'Canton-only' is explicit. It stops short of distinguishing itself from overlapping siblings like get_breaking_changes or get_upcoming_deadlines, leaving the agent to infer that radar is the aggregated curated feed.

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 concrete trigger conditions: 'Use when a user asks what's changing, what's about to break, or what deadlines are approaching on Canton.' That is clear when-to-use guidance. There is no when-not guidance and no named alternative for narrower queries, so it falls short of the 5 anchor.

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 readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description still adds real behavior: results are merged across heterogeneous sources and returned newest-first, with a default 7-day window and a Canton-only scope. It does not describe pagination or per-item shape, keeping it short of a 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?

Three dense sentences, front-loaded with the resource and scope, then the source list, then the disambiguation. No filler; every clause carries information an agent would otherwise have to guess.

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, no nested objects, and only 2 optional params, so the description's coverage of scope, ordering, sources, and the sibling alternative is sufficient to call it correctly. Nothing essential is omitted.

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 both parameters (days, limit) are fully documented with defaults and max bounds, so the schema does the heavy lifting. The description only restates the default window ('default last 7 days') and adds no syntax or semantics beyond that.

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?

Specific verb+resource ('chronological feed of recent Canton Network activity') with the merged sources enumerated (CIP status changes, grants, forum threads, blog posts, GitHub releases, radar items). Explicitly distinguishes itself from a git/repo changelog and from get_trending, so an agent can differentiate it from siblings.

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