prxhub

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

With no annotations, the description discloses key behaviors: batch processing, error short-circuiting on the first failure, and dependency on pre-registered sources. It does not cover potential side effects but is adequate for a write operation.

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

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

The description is concise, with two sentences and an additional note. It front-loads the batch purpose and follows with key usage details. No wasted words, though the structure could be slightly more organized.

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 the tool's complexity (array of objects with nested arrays, dependency on another tool), the description covers batch processing, error handling, and claim splitting. Without an output schema, it reasonably omits return value details.

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 50%, but the description adds meaning beyond the schema by explaining the batch behavior, error reporting per index, and the requirement for source_id to reference existing sources. It compensates for the schema's lack of detail on these aspects.

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 'Batch-friendly claim registration' and clarifies that it adds claims with evidence to a draft. It distinguishes itself from siblings like 'add_sources' and 'search_claims' by focusing on claim registration with evidence.

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 mentions that evidence.source_id must reference an already-registered source and that the first error short-circuits. It also advises on claim granularity ('split compound claims'). However, it does not explicitly state when not to use this tool or provide alternatives.

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

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

With no annotations, the description fully covers behavioral traits: sequential insertion, short-circuit on first error, cumulative results, and ID format conventions. This is sufficient for an agent to understand side effects.

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

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

The description is reasonably concise with three paragraphs, each serving a distinct purpose: batch behavior, ID convention, and inheritance use case. It is well-structured and 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?

Given 2 required parameters and no output schema, the description covers essential behavioral aspects and parameter usage. It could optionally mention the response format, but overall it is complete enough for correct tool invocation.

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

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

The description adds meaning beyond the schema by explaining the ID format (src-1, src-2) and the URL format for inherited bundles. With schema description coverage at 50%, this additional context is valuable.

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 clearly states 'Register one or more sources on a draft', which is a specific verb and resource. It distinguishes from siblings like 'add_claims' and 'start_draft' by focusing solely on source registration.

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

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

The description provides context like batch-friendly registration, ordering, and error behavior. It gives a concrete use case for inherited bundles. However, it lacks explicit when-not-to-use instructions or alternatives.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It does so by explaining that with a sessionId, the citation counts toward a publisher's contribution multiplier and trust tier uplift; without a session, it is recorded for audit but does not influence quota. It also notes 'Agent-authenticated only' and directs to an agent registration endpoint. However, it does not state whether the tool is read-only or potentially destructive, though the action of citing is inherently a write operation. A minor gap, but overall strong for a tool with no 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?

The description is concise: two short paragraphs with no fluff. The first sentence fronts the key usage guideline ('stricter than star_bundle'), followed by the pairing rule. Each subsequent sentence adds important behavioral or contextual detail. No word 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?

For a tool with 4 parameters, no output schema, and no annotations, the description covers all essential aspects: purpose, when to use, parameter effects (sessionId vs no session), authentication requirement, and pairing instruction. The agent can confidently decide when and how to invoke this tool, and what to expect from different usage patterns.

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 input schema covers 100% of parameters with descriptions. The description adds significant context beyond the schema: it explains the differential impact of providing sessionId (influences multiplier/trust uplift) vs omitting it (audit only, no quota impact). The schema's descriptions are brief (e.g., 'preferred', 'being cited'), so the description enriches understanding. The parameter semantics are well-addressed.

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 clearly states 'Cite a prxhub bundle in your answer' – a specific verb+resource pair. It further distinguishes itself from the sibling star_bundle by noting it is 'stricter' and should be used when facts/quotes/conclusions are actually pulled, not just browsed.

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

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

The description explicitly states when to use ('when you actually pulled facts / quotes / conclusions from the bundle') and when not ('not just browsed it'). It also mandates pairing with star_bundle for the same bundleId, giving clear instructions on combining tools.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it generates a short-lived HTTPS URL, returns raw bundle bytes, and handles private bundles with a 'not_found' error. However, it lacks details on rate limits, authentication needs, or exact URL expiration times.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by essential behavioral details. Every sentence adds value: the first explains the action and resource, the second describes the return value, and the third covers error handling. There is no wasted text.

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 the tool's moderate complexity (single parameter, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and key behaviors like URL generation and error handling. However, it could improve by mentioning response format or any prerequisites, though the lack of output schema doesn't severely impact completeness here.

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 input schema has 100% description coverage, with the 'slug' parameter well-documented. The description adds minimal value beyond the schema by mentioning the slug format as '<username>/<slug>' or '<org-slug>/<slug>', but does not provide additional syntax or format details. This meets the baseline score of 3 for high 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?

The description clearly states the specific action ('Generate a presigned download URL') and resource ('public .prx bundle on prxhub'), distinguishing it from sibling tools like 'preview_bundle' or 'assemble_bundle' which involve different operations on bundles. It precisely defines what the tool does without being tautological.

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

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

The description provides clear context for when to use this tool: for downloading public bundles via a presigned URL. It implicitly excludes private bundles by stating they return an error, but does not explicitly name alternatives or specify when not to use it compared to other bundle-related tools like 'preview_bundle' or 'assemble_bundle'.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it returns metadata and bundles, has scope limitations (public/unlisted only), and returns 404 for private collections. It doesn't mention rate limits, authentication needs, or pagination behavior, but covers the essential operational constraints.

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

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

The description is perfectly concise with two sentences that each earn their place. The first sentence states the core functionality, and the second provides crucial usage context and limitations. No wasted words, and information is front-loaded appropriately.

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 the tool's moderate complexity (3 parameters, no output schema, no annotations), the description provides good contextual completeness. It explains what the tool returns, when to use it, and important behavioral constraints. The main gap is the lack of output format details, but this is partially compensated by the clear purpose statement.

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 thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, but doesn't need to since the schema coverage is complete. Baseline 3 is appropriate 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?

The description clearly states the tool's purpose with specific verbs ('return', 'get') and resources ('collection's metadata', 'list of bundles inside it'). It distinguishes from siblings by specifying it's for retrieving existing collections rather than creating, listing, or modifying them.

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

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

The description provides explicit guidance on when to use ('Use before running fresh research so you don't re-synthesize what the workspace already contains') and when not to use ('Public/unlisted scope only — private collections return 404'), with clear alternatives implied (e.g., use list_collections to find collections first).

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

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

No annotations are provided, so the description carries the full burden. It mentions that collections are 'public' and owned by specific entities, which adds context about access and scope. However, it doesn't disclose behavioral traits like pagination, error handling, or rate limits, leaving gaps in operational transparency for a tool with no annotation support.

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

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

The description is appropriately sized and front-loaded, with the first sentence stating the core purpose. The subsequent sentences provide usage context without redundancy, and each adds value (e.g., practical scenarios and discovery benefits). There's zero waste, making it efficient and well-structured.

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 the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and context well, but lacks details on output format or error behavior, which would be helpful since there's no output schema. It compensates adequately but not fully for the missing structured data.

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 parameters thoroughly. The description doesn't add any parameter-specific semantics beyond what the schema provides (e.g., it doesn't explain 'owner' formats or 'sort' implications in more detail). Baseline 3 is appropriate as 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?

The description clearly states the tool's purpose with specific verbs ('browse', 'discovery') and resources ('public collections owned by a user, org, or agent'). It distinguishes this from sibling tools by focusing on listing collections rather than manipulating bundles or claims, making its role explicit and differentiated.

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

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

The description explicitly states when to use this tool: 'Use when you're about to publish a new bundle and want to ask the user which existing curated set it belongs to.' It also provides an alternative usage context ('discovery surface') and contrasts it with search results, giving clear guidance on its application versus other tools.

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?

With no annotations, the description carries the full burden. It discloses that the tool returns a manifest preview and warnings/recommendations, and the title clarifies it's non-destructive ('inspect without compiling'). However, it does not mention permissions or side effects.

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

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

The description is two sentences, clear and concise. It front-loads the output and provides a use case, with no wasted words.

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

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

For a simple tool with one parameter and no output schema, the description is fairly complete. It explains the output and a primary use case, though it could be slightly more explicit about the input.

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 0%, so the description must compensate. It does not mention the 'draft_id' parameter at all, leaving the agent to infer its meaning. The description could benefit from stating that draft_id is the identifier of the draft to preview.

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 clearly states it returns a manifest preview and warnings/recommendations, using the verb 'inspect' and resource 'draft'. It distinguishes from sibling tool 'publish_draft' by noting it's for a last-look before publishing.

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

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

The description gives a use case ('useful for a last-look before publish_draft'), providing context for when to use. However, it does not explicitly state when not to use or contrast with alternatives like validate_draft.

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?

With no annotations, the description fully carries the burden. It discloses that the server compiles the draft, appends a server-signed agent attestation, uploads the tarball, and returns the URL. Also mentions bundle size cap (50 MB) and that collection_slug is silently skipped if not owned. This exceeds basic expectations.

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

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

The description is relatively long but every sentence adds unique value. It is well-structured with purpose first, then workflow, prerequisites, and technical details. Minor deduction for length but fully justified by content density.

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 7 parameters, no output schema, and no annotations, the description covers the entire process: prerequisites, workflow, constraints (size cap, authentication), and outcome (returns URL). It lacks nothing essential for correct invocation.

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

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

Despite 100% schema coverage, the description adds significant meaning: explains slug derivation, default visibility, title override behavior, draft_id processing, and collection_slug's silent skip. This goes beyond what the schema provides.

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

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

The description clearly states the tool publishes a draft by draft_id, differentiating it from siblings like validate_draft or start_draft. It specifies the action and resource ('publish a draft to the registry') and outlines the server-side process (compile, sign, upload, return URL).

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 describes the prerequisite workflow: start_draft → add_sources → add_claims → set_synthesis, then call publish_draft. Also instructs on agent registration if not already bound, and provides context on bundle size limits. This clearly tells when and how to use the tool.

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?

With no annotations provided, the description carries the full burden. It discloses the 10-minute expiry, human-in-the-loop requirement, failure mode (expired_token), post-poll side effects (write identity to disk, session authentication), and the fact that agents don't hold signing keys. No contradictions.

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

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

The description is long but well-structured with sections and bullet points. Critical information is front-loaded. Every sentence adds value. Slightly verbose but appropriate for the complexity. Some redundancy 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?

No output schema, but the description covers return values (device code, approval URL), preconditions, post-poll actions, failure modes, and session implications. It is thorough for a complex flow, leaving no major gaps.

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 baseline is 3. The description adds significant context: for proposed_slug, it explains constraints and suggests patterns; for proposed_display_name, it describes editing possibility. It also explains the scopes override. This adds 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?

The description clearly states the tool starts the agent signup flow, returns a device code and approval URL, and distinguishes itself from the sibling tool register_agent_poll. The verb 'start' and the context of 'first contact' make the purpose unambiguous.

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?

Extensive guidance on when to call (no existing identity, human available) and when not to call (existing identity, headless/CI). Explicit step-by-step instructions for checking existing identity and handling the approval URL. Alternatives like checking identity files are clearly described.

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

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

No annotations provided, so description carries full burden. It details all four possible responses, the polling rate limit, the give_up mechanism after ~55 seconds, and consequences of continuing to poll (waste budget). Very transparent.

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?

Description is long but well-structured with bullet points and sections. Each sentence serves a purpose, though slightly verbose. Concise enough given the complexity.

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

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

No output schema, but the description fully explains return values and their meanings, including what to do on success (save bearer token). Covers all necessary context for a polling 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 (device_code) with 100% schema coverage. The description adds context by specifying it's the device_code from register_agent, which is beyond the schema's description.

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

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

Description clearly states it is a partner tool to register_agent for polling signup completion. It distinguishes from siblings by specifying the polling mechanism and response types.

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 call (every interval seconds, never faster), when to stop (on give_up, success, or error), and what to do on give_up (stop and inform user). Also references the partner tool register_agent.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. It reveals cache-first behavior, the type of search used (semantic, full-text, claim-rollup), and the return of a session_id for feedback. However, it does not mention rate limits, authentication needs, or error handling, which slightly reduces completeness.

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

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

The description is front-loaded with the critical 'cache-first' instruction and flows logically through the recommended steps. While it is dense and somewhat lengthy, every sentence contributes value. Minor verbosity prevents a perfect score, but overall structure is clear.

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 the absence of an output schema, the description outlines return values (top bundles, session_id) and usage of the slug via download_bundle. It provides enough context for an agent to understand how to chain calls, though a brief description of the bundle fields beyond slug would be beneficial.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining the session_id's role, providing an example format for the collection parameter, and integrating parameters into a larger workflow. This elevates the parameter understanding beyond schema alone.

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 clearly states it returns top public bundles by relevance using semantic, full-text, and claim-rollup search. It distinguishes itself from sibling search_claims by focusing on bundles and emphasizes a cache-first strategy, making its purpose specific and distinct.

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

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

The description explicitly instructs to call this before launching web research, provides a recommended multi-step flow involving download_bundle, star_bundle, cite_bundle, and session_feedback, and clarifies when to skip feedback. This offers clear usage context and alternatives.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the retrieval method (hybrid vector + full-text), sorting criteria (fidelity score), and that results reference parent bundles. However, it doesn't mention rate limits, authentication needs, or what happens if no results are found, leaving some gaps for a search tool.

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

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

The description is efficiently structured in two sentences: the first states purpose and method, the second explains returns and references to sibling tools. Every sentence adds value with zero waste, making it easy to parse and front-loaded with essential 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?

Given the tool's moderate complexity (search with three parameters), no annotations, and no output schema, the description does well by explaining the retrieval method, sorting, and bundle references. However, it doesn't describe the output format (e.g., structure of returned claims) or error conditions, leaving some completeness gaps despite good coverage.

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 fully documents all three parameters (query, limit, confidence). The description doesn't add any parameter-specific semantics beyond what's in the schema, such as explaining how the query interacts with the hybrid retrieval or what fidelity score means. Baseline 3 is appropriate when 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?

The description clearly states the specific action ('search extracted claims'), resource ('across public .prx bundles on prxhub'), and method ('using hybrid vector + full-text retrieval'), distinguishing it from siblings like search_bundles or download_bundle. It explicitly mentions what it returns ('top claims sorted by fidelity score') and references parent bundles.

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

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

The description provides clear context for when to use this tool ('search extracted claims') and implicitly suggests an alternative by mentioning that claims reference parent bundles which can be passed to download_bundle. However, it doesn't explicitly state when not to use it or compare it directly to other search tools like search_bundles.

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

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

No annotations are provided, so the description must carry the full burden. It mentions 'Agent-authenticated only' and 'Voluntary feedback channel,' but lacks details on side effects, data handling, or consequences of calling the tool. More behavioral context would improve transparency.

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

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

The description is concise (3 sentences) and front-loaded: first sentence defines purpose, second gives usage conditions, third details parameters. No unnecessary words, 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?

For a feedback tool with 4 parameters and no output schema, the description covers purpose, usage, and parameter semantics. It could be improved by mentioning what the tool returns or any confirmation behavior, but it is largely complete for the agent to use 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?

With only 25% schema description coverage, the description adds significant meaning: it explains that sessionId comes from a prior search, that bundles/claims/sources can be any combination with specific flags, and that empty arrays are legal. This compensates well for the schema gap.

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 clearly states it's a 'voluntary feedback channel' and specifies it should only be called when the user explicitly asks or when retrieval issues occur. This distinguishes it from search tools like search_bundles and search_claims, making its purpose unambiguous.

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

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

The description provides explicit guidance: when to call (user asks or issues) and when not to (smooth runs). It also explains how to structure input, including the meaning of empty arrays, which serves as a usage rule for the agent.

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?

With no annotations, the description discloses key behaviors: it is safe to call multiple times (idempotent) and each call replaces the specified fields. However, it does not cover permissions, error states, or side effects on unspecified fields, which would elevate the score to 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?

The description is three sentences, each serving a distinct purpose: purpose, idempotency, and use case. No redundant words, and front-loaded with the core action.

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 the tool's complexity (5 parameters, nested objects) and no output schema, the description covers the primary use case and idempotency. However, it lacks details on error handling, validation rules for nested objects, or the return value, which would be needed for full completeness.

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 low (20%), and the description lists the parameters but adds little beyond naming them. It mentions 'title' and its necessity for publishing, but does not elaborate on the structure of 'producer' (nested object) or constraints on 'tags' and 'providers', leaving semantic gaps.

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 uses a specific verb ('Patch') and lists the resources ('title / tags / producer / providers'), making the tool's purpose clear. It distinguishes itself from siblings like 'start_draft' and 'publish_draft' by mentioning the use case of adding a title after the draft starts.

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

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

The description explicitly states when to use this tool ('Use this to add a title before publish_draft if you skipped it at start_draft') and implies when not to use it (if metadata was already set). It also references a sibling ('publish_draft') and explains a consequence ('hard-fails without 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?

With no annotations, the description carries full burden and delivers: it states each call replaces the previous value (destructive), explains the citation system, and gives formatting rules. It fully discloses the tool's 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?

The description is well-structured: starts with definition, then recommendation, then key behavior (replaceable), then detailed citation rules. Every sentence earns its place with no redundancy.

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

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

The description is thorough for usage but lacks mention of return values or success signals. Given no output schema, a note on what the tool returns would improve completeness, but the core usage is well covered.

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 description extensively covers the 'markdown' parameter's content and format, but does not mention the 'draft_id' parameter at all. With 0% schema description coverage, more balance was needed, but the markdown details are thorough.

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 title and description clearly state the verb 'replace' and the resource 'synthesis markdown on a draft', distinguishing it from siblings like add_sources or set_metadata. It specifies what the tool does with precision.

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

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

The description provides explicit guidance: safe to call multiple times, 400+ character recommendation, citation format with inline [src-N] tokens, grouping rules, placement at sentence end, and hyphens only. These guidelines help the agent use the tool correctly.

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?

The description discloses idempotency behavior: re-starring returns success with already_starred=true. It also notes authentication requirements. Since no annotations are provided, the description fully carries the burden, and it does so well. Minor deduction for not specifying the return format or any side effects beyond idempotency.

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

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

The description is concise, with three sentences that each serve a distinct purpose: explaining the action, differentiating from cite_bundle, and noting idempotency and auth. No redundant or irrelevant 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?

Given a simple tool with 1 required parameter, no output schema, and no annotations, the description covers purpose, usage, behavior, and authentication. It could optionally mention the response format or any error cases, but for the tool's simplicity, it is adequately complete.

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

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

The input schema has 100% coverage, with a single required parameter 'bundleId' that is well-described as coming from search_bundles results. The description adds no additional meaning beyond the schema's description, which already specifies the format and source. 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 clearly states the tool's purpose: it endorses a bundle publicly, indicating it was useful. The verb 'star' combined with 'Public-style endorsement' makes the action unambiguous. It distinguishes itself from the sibling cite_bundle by explicitly stating 'Pair with cite_bundle when your answer actually used the bundle's content.'

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

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

The description provides explicit guidance on when to use this tool versus cite_bundle: use star_bundle for general endorsement, use cite_bundle when content is actually used. It also states that this is agent-authenticated only, and clarifies agent account creation via a separate endpoint, setting prerequisites.

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?

With no annotations, the description discloses the draft_id TTL (1h), no auth requirement, and the dependency chain. However, it does not discuss behavior on multiple calls or potential side effects beyond returning an id.

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?

Reasonably concise with clear structure: purpose, pre-conditions, parameter details. Could be slightly tighter but front-loads the key action.

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?

Covers main aspects needed for a start_draft tool: purpose, sequence, parameter details, and return value. Lacks discussion of edge cases like expired drafts or error scenarios.

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?

Despite only 40% schema coverage, the description adds significant meaning for title, producer, and providers with usage examples and requirements. Tags and query lack additional explanation.

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 clearly states 'Open a composable draft' and explains it returns a short-lived draft_id for subsequent draft operations. It distinguishes from sibling tools by positioning itself as the entry point for drafts.

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 outlines a before-calling workflow ('always run search_bundles / search_claims first') and gives specific steps for reusing prior bundles. Provides context on when to use this tool versus alternatives like set_metadata.

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?

Describes the three output bands in detail and their blocking/non-blocking nature. However, given no annotations, the description does not explicitly state that the tool is read-only or has side effects, leaving some ambiguity about mutability.

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 with bullet-like formatting for the bands. No extraneous words, front-loaded with the main result, and efficiently conveys the core logic.

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?

Captures the essential behavior and publishing condition, but lacks parameter description and prerequisites (e.g., draft must exist). For a simple tool, it is adequate but has noticeable gaps.

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 sole parameter draft_id is required but not described in either the input schema (0% coverage) or the description. The agent must infer its meaning from context, which is a significant gap.

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

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

Clearly states the tool 'returns three bands for a draft-in-progress' (errors, warnings, recommendations) and explicitly distinguishes itself from the sibling publish_draft by noting the condition for calling it. The verb 'validate' and resource 'draft' are specific.

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 (on a draft-in-progress) and that clearing errors means you can call publish_draft. Despite not listing when not to use, the context signals and mention of publish_draft provide good 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?

Despite no annotations, the description fully discloses the tool's behavior: it's a read-only identity check. It lists the response fields including optional ones, giving complete transparency.

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 paragraphs: purpose, usage guidelines, response structure. Every sentence adds value. No fluff.

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 zero parameters and no output schema, the description fully covers what the tool does, when to use it, and what it returns. No gaps.

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?

No parameters exist, so baseline is 4. The description does not need to add parameter meaning as there are none. Schema coverage is 100% trivially.

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 tool name 'whoami' and title 'Report the current session's identity' are clear. Description states it returns the identity as seen by the server, distinguishing it from all sibling tools, none of which report session identity.

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 provides when to use: when unsure about authentication, after register_agent_poll, as first-call diagnostic. Also implies when not to use (avoid write tools). This is exceptional guidance.

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