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

The description adds substantial behavioral detail beyond the annotations: agents run in the background, each responds to the first prompt, then reviews other responses, and results should be followed with get_jam_results. This explains the asynchronous flow and interaction pattern, which is valuable context for a mutation 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 short and front-loaded, with the main behavior stated first and a compact Args section for parameter guidance. Every sentence contributes useful information without 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?

Given an output schema exists and annotations declare mutation but not destructive behavior, the description covers the key operational context: prerequisites, async behavior, parameter sources, and the follow-up retrieval tool. No critical information needed to invoke the tool correctly appears to be 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?

With 0% schema description coverage, the description compensates by explaining that jam_id is an active Jam created by the caller and that agent_ids are Knowledge Agent IDs from list_knowledge_agents. It does not describe array constraints such as duplicate handling or maximum count, so it falls short of fully fleshing out all parameter 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 states a specific action: having Knowledge Agents participate in an active Jam the caller created. It distinguishes this from sibling tools like launch_jam by specifying the Jam must already be active and created by the caller, and by naming the follow-up tool get_jam_results.

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 clear usage context: the Jam must be active and created by the caller, agent IDs come from list_knowledge_agents, and results are retrieved via get_jam_results. It does not explicitly state when not to use this tool or compare it directly against launch_jam, which keeps it from 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=false and destructiveHint=false, so the write-without-destruction profile is covered. The description adds genuine value by explaining that text is split into passages and that source details are stored per passage for citations, but omits processing timing/indexing behavior, which matters given the get_document_status sibling implies asynchronous ingestion.

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 result, then a compact per-parameter block. A sentence or two is slightly redundant with the Args list (e.g. 'keeps its source' vs. the source_* params), but overall 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?

An output schema exists so return values need not be explained, and the description covers ownership, chunking, and citation metadata. The main omission is what happens after the call (async processing, need to poll via get_document_status).

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 carries the full burden, and the Args block defines all seven parameters meaningfully — including format hints such as ISO 8601 for timestamp and example values ('web', 'note', 'transcript', 'email') for source_type. Minor gap: it doesn't state which parameters are optional or their defaults.

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 ('Add text ... as a new document') targeting a Knowledge Agent, and clarifies the source metadata is retained. It doesn't explicitly contrast with the sibling upload_document, but the 'text' framing makes the distinction reasonably inferable.

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 'a Knowledge Agent you own' implies an ownership precondition, but there is no explicit when-to-use versus upload_document or other ingestion tools, and no mention of failure modes or size limits.

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?

Adds substantial context beyond the thin annotations: it explains what a citation means (checked evidence vs agent reasoning), that referenced mode returns verbatim passages with no model writing, and importantly that each question is recorded in the agent's query history — which is exactly why readOnlyHint is false despite this being a questioning tool. It also warns that 'confidence' is a retrieval score, not a correctness signal.

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

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

Front-loaded with purpose, then the interpretive field notes, then Args — a sensible order with little padding. It runs long and restates defaults already present in the schema, but nearly every sentence carries decision-relevant meaning.

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 4-parameter tool with an output schema, an empty schema description, and minimal annotations, this covers everything an agent needs: mode selection, how to interpret the returned answer and accompanying fields, and the query-history side effect. Nothing material is left to guess.

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 carries the full burden and does so for all four parameters, including where agent_id comes from (list_knowledge_agents), the mode enum values plus the omit-to-use-agent-default behavior, and max_chunks' default of 5. Only the agent_id pattern constraint and any bounds on max_chunks are left unstated.

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?

Opens with a specific verb+resource+output: 'Ask a Knowledge Agent a question and get an answer from its documents, with citations.' This is clearly distinct from siblings like list_knowledge_agents (enumeration) or read_document (raw document retrieval).

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 guidance for the generative vs referenced mode choice and states the abstention behavior when documents don't cover the question. It does not, however, say when to reach for this tool versus read_document or check_corpus_quality on the same data, so the sibling routing 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?

readOnlyHint=true is consistent with 'returns a summary and the flagged documents only', and the description adds real value beyond annotations by enumerating the four damage classes detected and clarifying that output is filtered, not a full dump. It omits cost/latency expectations for scanning an entire corpus, which for a potentially long-running scan would be useful.

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 the damage categories are front-loaded and the prose is tight. The trailing 'Args:' block mostly duplicates the input schema's title and pattern, adding length without adding 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 an output schema present, the return-value gap is covered, and the read-only annotation covers the safety profile. What remains thin is the single undocumented parameter and the absence of any note on scan scope or duration for a corpus-wide check.

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 carry the load, and 'agent_id: Knowledge Agent ID' only restates the schema title with a slight disambiguation (Knowledge Agent vs Jam). It does not explain the ID format constraint or where the agent ID comes from, but for a single required scalar parameter this is the minimum viable.

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 damaged documents in a Knowledge Agent's corpus') plus the deliverable ('recommended fix for each'). No sibling tool performs corpus quality inspection, so it is unambiguously distinguishable from list_documents, read_document, and get_document_status.

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 symptom statement ('Damaged text makes an agent miss topics its documents hold') implies a trigger condition, but the description never says explicitly when to run this, whether it should precede upload/ask_knowledge_agent, or whether there is any alternative to use instead. Usage is inferable 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 indicate this is not read-only and not destructive, and the description adds important behavioral context: it creates a draft, nothing is sent until launch_jam, agents start only at launch, and the result includes green_room_url. It does not cover auth or rate-limit concerns, so it is strong but not exhaustive.

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 key distinction from launch_jam and then uses a structured Args section for the 12 parameters. It is somewhat long, but most of the length is justified by the low schema description coverage and the need to explain prompt semantics.

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 complex 12-parameter creation tool with no schema descriptions but an output schema, the description is complete: it covers draft behavior, launch behavior, prompt types, agent constraints, all parameter meanings, and the returned green_room_url. Nothing critical appears missing for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so well: it defines all 12 parameters, explains prompt types and seed_reasons, clarifies that agent_ids come from create_knowledge_agent or list_knowledge_agents, and says community_id comes from list_my_communities.

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 ('Create a draft Jam from a plan') and immediately distinguishes it from the sibling launch_jam by clarifying that nothing is sent until launch. An agent can tell exactly what this tool does and how it differs from launching or listing Jams.

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 explains when to use this tool versus launch_jam, and gives important usage constraints such as Knowledge Agents-only Jams requiring agent_ids with no invite_emails and only one prompt per agent Jam. It also explains prompt-type behavior and participant flow.

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 only declare readOnlyHint=false and destructiveHint=false; the description adds real context — the new agent is private by default and empty, the system prompt need not instruct document restriction because that is enforced already, and backfill answers are labeled. It doesn't cover rate limits or duplicate-name behavior, so not 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 purpose, then workflow, then a clean Args block. Slightly long, but nearly every sentence carries distinct information; the only marginal item is the Jam orchestration paragraph, which is useful but 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?

For a 6-parameter creation tool with an output schema present (so return values need not be described), the description covers purpose, default state, parameter semantics, and the surrounding workflow. An agent has everything needed to call it correctly on the first attempt.

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 0%, so the description carries the full burden and does: it explains all six parameters, including the two enum values of mode ('generative' cites passages vs 'referenced' returns them verbatim), the source of community_id (list_my_communities), and the labeling behavior of allow_foundation_backfill. This is meaningfully more than the schema conveys.

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 ('Create a Knowledge Agent that you own') and immediately gives the resulting state ('private, no documents yet'). This distinguishes it cleanly from update_knowledge_agent, set_knowledge_agent_visibility and list_knowledge_agents among the 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?

Explicitly routes the agent to the follow-on tools: upload_document/add_text_document to populate, set_knowledge_agent_visibility to share, create_jam to orchestrate multi-agent discussion, plus the note that sharing is not required for Jam participation. This is exactly the when-and-what-next guidance most definitions lack.

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 destructiveHint=true, so irreversibility is partly redundant, but the description adds the ownership/authorization requirement (“you own”) and the practical consequence (must re-upload the file to restore), which annotations cannot convey.

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 action, then the irreversible warning, then the repair recipe, then args. Each part is useful, though the remediation sentence is slightly tangential to a caller intentionally deleting.

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?

An output schema exists so return values need no explanation; ownership, irreversibility, and parameter provenance are all covered for a two-parameter destructive call. Only ID format details are 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 0%, so the description must carry the load; it explains that agent_id must correspond to an owned agent and that document_id comes from list_documents, providing provenance guidance absent from the bare string schema. It still omits the expected ID format/pattern.

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 (delete) and resource (document), plus the scope constraint (a Knowledge Agent you own), which separates it from sibling list_documents/read_document/upload_document. The remediation sentence also positions it relative to upload_document.

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 concrete when-to-use case (fixing a damaged document) and the alternative workflow (delete, then re-upload the original). It does not explicitly say when *not* to delete, e.g. versus a hypothetical replace/update path, but the routing intent is clear.

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 declare readOnlyHint=true, so safety is covered; the description adds the status lifecycle (pending/processing → completed with passage count or failed with error), which tells the agent this is a poll-until-terminal operation. It doesn't state rate limits or polling cadence, which keeps 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?

Purpose is front-loaded in the first sentence, followed by the trigger condition and the status semantics; the arg list is short and earns its place. Minor noise from an unbalanced quote around "processing" but nothing substantive 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 two-parameter read-only status check with an output schema present, the description covers what it does, when to call it, and how to interpret each returned status. Return-value detail is correctly left to the output schema.

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 carry parameter meaning — and it does, labeling agent_id as the Knowledge Agent ID and document_id as coming from upload_document. It doesn't describe the ID format/pattern, but the provenance hint is the more useful information.

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 — shows whether text extraction of an uploaded document has completed — and is clearly distinguishable from siblings like list_documents and read_document. The description also names the upstream tool (upload_document) that produces the document_id, anchoring it in a workflow.

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 to use it when upload_document returned "processing", which is a concrete trigger condition. It doesn't name an alternative (e.g., read_document once completed), but the polling context is clear enough for correct selection.

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 only declare readOnlyHint=true, so the description carries the rest and does add real context: the response is permission-scoped ("The Jam's creator also sees its invitees and the agents chosen for the draft"), meaning output varies by caller role. It also discloses that prompts carry probability and reasoning-length metadata. It does not mention pagination or failure modes, 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?

Front-loaded with the core purpose, then what is returned, then the args block. Every sentence carries information; the only minor inefficiency is the slightly fragmented second sentence about prompt fields.

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?

An output schema exists, so return shape needn't be spelled out, yet the description still covers it at a useful level plus the role-dependent visibility caveat and ID provenance. For a one-param read tool 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?

Schema description coverage is 0% for the single jam_id param, so the description must compensate, and it does by stating the value's provenance (from list_jams or create_jam) – genuine guidance beyond the bare string pattern. It doesn't restate the pattern constraint, but that is already in 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 opening sentence names a specific verb and resource ("Show a Jam") and enumerates what comes back: description, status and ordered prompts. It implicitly separates itself from list_jams and the get_jam_results/get_jam_responses siblings by framing this as the single-Jam detail read, though it never names them 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?

There is no explicit when-to-use / when-not comparison against list_jams or get_jam_results. The only routing signal is the arg note telling the agent where the ID comes from (list_jams or create_jam), which implies the intended workflow but leaves the choice of tool 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?

readOnlyHint=true already tells the agent this is a safe read, and the description adds real behavioral context beyond that: author_type 'seed' for plan seed ideas, the meaning of [n] citation markers, and that probability is the author's estimate for prediction prompts. It does not mention pagination or size limits on the response set.

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 return shape are front-loaded in the first sentence, with secondary semantics (citations, seed authors, probability) after. The citation/read_document aside is slightly tangential but earns its place by preventing misuse.

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 an output schema present, the description needn't explain the return shape, and it still clarifies the semantic meaning of fields (probability, author_type, citation markers). Only the thin coverage of jam_id keeps it from being 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 0%, so the description carries the burden. It explains prompt_order well ('the first is 0', scoped to a prompt, sourced from get_jam) but jam_id gets only a trivial gloss ('Jam ID'), leaving format expectations unstated beyond the schema pattern.

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 opens with a specific verb and resource ('Read the responses in a Jam') and enumerates exactly what is returned: author, probability, text, citations. It does not explicitly contrast itself with the closely named sibling get_jam_results, so an agent still has to infer that difference.

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 it to see what each Knowledge Agent said' gives a clear usage context, and it routes the agent elsewhere for two related needs ('from get_jam' for prompt ordering, read_document for citations). It stops short of naming an alternative tool 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 readOnlyHint=true, so safety is covered. The description adds genuine semantic context beyond that: the caveat that funnel counts are cumulative and not completion indicators, and that failed or abstaining agents contribute nothing. That is real interpretive guidance an agent could not infer from 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-loads the one-line summary before detailing each result key, and every sentence carries information. The quoted-key walkthrough is slightly dense but each entry explains a distinct output field rather than 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?

An output schema exists, yet the description still gives enough framing for the result categories and their interpretation to orient an agent. With one required parameter and readOnly annotations, nothing needed to invoke the 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 0%, and the description only restates "jam_id: Jam ID." with no added meaning about where the ID comes from or how it relates to sibling calls. The parameter is largely self-evident and the schema carries the pattern constraint, so this lands at the baseline rather than lower.

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 ("Show a Jam's results") and enumerates the three output dimensions: participation, mean probabilities, top ideas. It also implicitly distinguishes itself from get_jam_responses by framing this as aggregate results rather than per-response data.

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 to get_jam_responses when it needs to follow individual agents, and explains that "funnel" reflects cumulative activity rather than Jam completion. Lacks an explicit statement of when this tool should be called (e.g., after launch), but the alternative is named clearly.

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?

Goes well beyond the annotations by disclosing irreversibility ("This cannot be undone"), the outbound email side effect, and that Knowledge Agents begin responding in the background. The irreversibility note sits in mild tension with destructiveHint=false, but since the description warns explicitly rather than hiding the risk, it informs rather than misleads. It does not mention permission/auth requirements for launching.

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 action and its consequence, then side effects, then follow-up routing, then args — a logical order with no filler. The Args block mildly duplicates the schema's default for send_invitations, but each line adds a constraint or effect.

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 two-parameter, irreversible state-transition tool, the description covers preconditions, side effects, background work, and the follow-up tool; an output schema exists, so return values need not be explained. Nothing an agent needs before calling 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 0%, so the description must carry both parameters, and it does: jam_id is constrained to a draft Jam you created (state + ownership), and send_invitations is explained as sending the invitation emails with the default noted. The jam_id entry is still thin on format, but the pattern constraint lives in 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 (launch a draft Jam) with an ownership/state scope ("a draft Jam you created"), which cleanly separates it from create_jam and get_jam in the sibling list. The immediate follow-on sentence ("The Jam becomes active") makes the resulting state change explicit.

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 prerequisites and alternatives directly: check the draft with get_jam first, and follow the run with get_jam_results. It also constrains the input to drafts you created, so an agent knows this is not for already-active Jams.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is light but it adds essentially nothing behavioral: no mention of pagination, result ordering, corpus size limits, or whether all documents are returned in one call. The only added detail is the conceptual scoping to a single agent's corpus, which is really purpose rather than 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?

One summary sentence front-loads the operation and scope, followed by a compact Args block with zero filler. The Python-docstring "Args:" formatting is slightly out of place for a tool description but costs nothing in 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?

For a one-parameter read tool with an output schema and a readOnlyHint, the essentials are present and the ID provenance is covered. What's missing is the enumeration contract an agent needs before calling — whether results are paginated/truncated and how they're ordered.

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% and the schema only supplies a regex pattern, so the description carries the load — and it does, identifying agent_id as the Knowledge Agent ID and telling the caller where to get it (list_knowledge_agents). Minor gap: it doesn't clarify that an ID (not a display name) is required beyond the wording.

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 with an explicit scope ("documents in a Knowledge Agent's corpus"), which distinguishes it from read_document, upload_document, get_document_status, and delete_document. It never explicitly names those siblings, but the list-vs-single-read distinction is inferable from the wording.

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 only: you use it to enumerate an agent's documents, and the Args note routes the caller to list_knowledge_agents to obtain the ID. There is no statement of when to prefer this over read_document/get_document_status or any prerequisite/exclusion 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?

With readOnlyHint=true already declaring the safety profile, the description still adds real behavioral context: the visibility scope of results and the fact that drafts are omitted until launched — a non-obvious filtering rule an agent would otherwise misread as missing data. It doesn't discuss result volume or ordering, but the output schema covers the return shape.

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?

Scope is front-loaded in the first sentence and the draft exclusion is placed immediately after, where it matters most. The relation enumeration is somewhat undirected in its framing (it never says whether relation is input or output), which costs a little clarity for the space it occupies.

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-optional-parameter read tool with an output schema and a readOnlyHint, the description supplies everything needed to call it correctly: what appears in the list, what is excluded, and where community_id comes from. Return-value detail is rightly left to the output schema.

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 0%, so the description must carry the single parameter, and it does: community_id is explained as an optional community filter with its upstream source (list_my_communities). Minor deduction because the 'relation' paragraph reads like a filter argument that does not exist in the schema, which could confuse an agent about available inputs.

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 and resource ('List the active Jams') with an explicit scope: created by you, participated in, or public. That scope makes it distinguishable in practice from get_jam (single Jam) and the creation/launch tools, though no sibling is named directly.

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 states inclusion criteria (created/contributing/public) and a key exclusion ('Your own drafts are not listed until you launch them'), and it routes the agent to list_my_communities as the source for community_id. It does not cover when to prefer get_jam or get_jam_results instead, so it stops short of full when/when-not 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?

The readOnlyHint annotation already establishes that this is a safe listing operation. The description adds useful behavioral context: which agents are included based on visibility and administrator status, and what the 'mode' and 'allow_foundation_backfill' fields mean, including that foundation-backfill answers are labeled.

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 action and scope, then adds definitions for fields an agent may encounter. It is appropriately sized, though the multiple quoted field explanations make it slightly less tight than a maximally concise definition.

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 parameters, an output schema present, and readOnlyHint=true, the definition provides enough context to call the tool correctly. It explains visibility scope, administrator behavior, and key output concepts, so no critical information 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?

There are zero input parameters, so parameter semantics are not a major concern and the baseline is 4. The description instead explains relevant output-field concepts such as 'mode' and 'allow_foundation_backfill,' which adds context beyond the empty input 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 states a specific verb and resource: 'List the Knowledge Agents you can ask.' It immediately clarifies scope by distinguishing the user's own agents from other people's published agents, making the tool's 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 wording implies that this tool is used to discover agents that can later be asked questions, and it references ask_knowledge_agent for the meaning of mode. However, it does not explicitly say when to call this tool versus alternatives, nor does it state exclusions or 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?

Annotations already declare readOnlyHint=true, and the description adds useful context that results are scoped to communities the caller belongs to and include the default community. It does not discuss pagination, but an output schema exists, reducing that burden.

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, with the core action front-loaded and the follow-up sentence explaining why the returned community ID matters. 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?

For a zero-parameter read-only listing tool with an output schema and readOnlyHint annotation, the description covers what the tool returns and why the result is useful. No critical context 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 has zero parameters, so the baseline is 4. The empty input schema and description are aligned; no additional parameter semantics are needed.

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: listing communities the caller belongs to, plus the default community. The resource is clearly distinct from sibling tools such as list_jams and list_knowledge_agents.

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 second sentence implies when a community ID is useful: placing a new agent or Jam, or sharing a Knowledge Agent. However, it does not explicitly say when to call this tool versus sibling listing tools or mention 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 establish readOnlyHint=true, so safety is covered. The description adds genuinely non-obvious behavior: text is reconstructed from stored passages, each prefixed with a 'title | Part n of m:' header, and neighboring passages can overlap — crucial for interpreting the returned text. It stops short of describing truncation behavior when max_chars is exceeded.

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

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

Purpose is front-loaded in the first sentence, followed by the output-format caveat and a compact Args block. Every sentence carries information; the Args section earns its place because the schema has no descriptions.

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?

An output schema exists and the description still explains the passage-reconstruction quirks, which is the right thing to document. What's missing is how the tool relates to siblings (status checks, Q&A) for a corpus that has many adjacent document tools.

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 carries the full burden and largely meets it: agent_id and document_id are identified, document_id is given a provenance path, and max_chars is explained as a character cap with its default. The string patterns and min bound are left to the schema, which is acceptable.

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 ('Read the text of a document in a Knowledge Agent's corpus') and anchors it with a concrete use case (checking a citation). It does not distinguish itself from siblings like ask_knowledge_agent or get_document_status, so an agent must 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 'for example to check a citation' implies when the tool is useful, and document_id sourcing ('from list_documents or an answer's citations') hints at workflow. There is no explicit when-not-to-use guidance or comparison against the sibling tools that also touch documents.

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 destructiveHint=true, and the description usefully explains what each visibility level exposes (e.g. 'public: anyone with the agent's link, without signing in'). However, it never states that changing visibility can revoke existing users' access or that the change is a security-sensitive mutation, which is the key behavioral fact the destructive hint implies.

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 one-line summary followed by enum semantics and an Args block, with no filler. Minor redundancy in restating the visibility values twice (prose and Args), but the repetition is compact.

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?

An output schema exists and the destructive mutation is well framed by the audience definitions, so the description is largely sufficient. It could say more about reversibility and the effect on current members, but nothing needed to pick the right value 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 0%, so the description carries the full burden and does: it defines all three parameters, gives the meaning of each enum value, and specifies that community_id is required for 'community' and should come from list_my_communities. That is meaningfully more than the raw 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: setting who can access ('ask') a Knowledge Agent you own. This is clearly distinct from update_knowledge_agent and the create/list siblings, so an agent can route here 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?

The four visibility values are each defined in terms of audience, which is the real decision the caller faces, and list_my_communities is named as the source for community_id. It does not explicitly contrast this tool with update_knowledge_agent or state when not to use it, so it stops short of full alternative 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?

The annotations already declare this is not read-only and is destructive. The description adds useful behavioral detail: omitted settings retain their values, and system_prompt replaces the existing prompt. It does not fully explain the destructive implications or permission requirements beyond ownership, but it meaningfully supplements the annotations.

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

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

The key update semantics are front-loaded, followed by a compact Args list. Every line adds useful parameter meaning or update behavior, with no redundant 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?

The description covers the partial-update behavior, ownership requirement, and each input parameter, while output details are covered by the existing output schema and safety signals by annotations. It is complete enough to call correctly, though it could say more about destructive consequences or visibility separation.

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 carry parameter meaning. It documents all six parameters, including enum-like mode values and that model applies to generative answers; model's allowed values are left to the schema, but overall the description compensates well for the missing schema descriptions.

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 clear verb and resource: 'Change the settings of a Knowledge Agent you own.' It is distinguishable from create/list tools, but it does not explicitly differentiate from the sibling set_knowledge_agent_visibility or explain that visibility is handled elsewhere.

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 'Change the settings' and the ownership prerequisite, so an agent can infer this is for updating an existing agent the caller owns. However, there is no explicit when-to-use guidance, no named alternatives, and no exclusions versus create_knowledge_agent or set_knowledge_agent_visibility.

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?

Goes well beyond the annotations: discloses the 45-second wait window, the three possible status outcomes with their payloads, the accepted file formats, and the ownership requirement on agent_id. That is exactly the operational context an agent needs before invoking a write 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?

Front-loaded with the action, then formats, then wait/status behavior, then args. The Args section slightly duplicates the schema, but each line still adds meaning; 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?

Covers inputs, ownership preconditions, accepted formats, timing, and outcome states; an output schema exists so return-value shape needn't be restated. 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 coverage is 0%, so the description carries the burden and does so: agent_id is constrained to an agent 'you own' (not just any ID), and path is clarified as being on the machine running the server, not the caller's machine — a critical disambiguation absent from the bare 'Path' title.

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 ('Upload a file ... to a Knowledge Agent') plus the distinctive blocking behavior ('wait for its text'). It is clearly separable from siblings add_text_document (text not file) and get_document_status (status polling).

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 async case ('processing' -> check later with get_document_status) and a consent constraint ('Upload only files the user chose'). It doesn't state when not to use it (e.g. prefer add_text_document for raw text), but the context is otherwise clear.

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