Sortition Knowledge

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

No annotations, so the description carries the full burden. It usefully discloses the return payload ('complete text of one page'), but omits whether page numbers are 0- or 1-indexed, what happens for out-of-range pages, and any size/rate limits.

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

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

Two tight sentences with zero waste; the action and return value come first, the usage cue second. Nothing redundant.

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 two-parameter read tool with no output schema, the description covers the essentials of what is returned and when to call it, but leaves parameter format (page indexing, document identifier) unspecified, which is a real gap given 0% schema 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 0% for both required parameters. The description only implies that 'page' is a page number and 'document' identifies the PDF, adding no format, identifier scheme, or indexing base detail that the schema lacks.

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 (Retrieve) and resource (complete text of one page from a PDF source document), which is unambiguous and distinguishable from list_documents and get_sortition_overview. It does not explicitly say how it differs from search_knowledge beyond sequencing, so it falls short of full sibling differentiation.

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

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

Gives clear usage context: 'Use this after search_knowledge() when more context or source verification is needed.' This tells the agent when to reach for it relative to a named sibling, but provides no exclusions or guidance on 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?

With no annotations, the description must carry behavioral disclosure. It implies a read-only informational call but does not explicitly state safety, side effects, auth needs, or return form. For a zero-parameter overview tool this is tolerable but not rich.

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

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

A single sentence with no filler, front-loading the purpose. Every word earns its place.

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

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

For a zero-parameter, no-annotation overview tool, the description states what information it supplies. It omits explicit read-only/safety framing and invocation context, but the low complexity and absence of an output schema keep those gaps minor.

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 parameters, so the baseline is 4. The empty schema and 100% coverage leave nothing for the description to clarify; it adds no parameter detail because none exists.

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 ('Describe') and names the resource ('Sortition Knowledge MCP server') while specifying the covered aspects: purpose, scope, and recommended use. It is clearly distinct in kind from the document/page/search siblings, though it does not explicitly mention 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?

No when-to-use guidance, prerequisites, or alternatives are stated. 'Recommended use' is content the tool returns, not invocation guidance, so an agent gets no explicit routing condition versus get_document_page, list_documents, or search_knowledge.

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 disclosure burden, but the verb 'List' plus 'currently available' implies a non-destructive read of a dynamic set. It says nothing about pagination, result size, or ordering, which are the behavioral traits that matter for a listing endpoint.

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

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

A single front-loaded sentence with no filler; the scope qualifier ('currently available') is placed where it is most useful.

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 described, and a zero-parameter read tool has a low bar. The only gap is that it never positions itself relative to its siblings, which an agent would need when deciding between listing and searching.

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

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

Zero parameters are declared (schema coverage 100%), so there is no parameter semantics to convey and the baseline of 4 applies.

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

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

States a specific verb (List), resource (source documents), and scope (Sortition knowledge base), so the agent knows exactly what it returns. It does not name or distinguish itself from siblings like search_knowledge or get_document_page, but the verb makes the enumeration intent 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. The agent must infer that this is the bare enumeration tool versus search_knowledge for filtered queries, which is exactly the distinction that needs stating.

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 behavioral burden. It discloses that the operation is semantic (not keyword) and that results include source excerpts with name, page and score, which is useful, but it omits any note on limits, empty-result behavior, or scope constraints. Return shape is already covered by the output schema.

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

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

Three tight sentences with no filler; the core capability and usage guidance are front-loaded, and the return description comes last where it belongs.

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

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

For a simple two-parameter search tool with an output schema, the description covers the main intent and rough return format. The unaddressed 'limit' parameter and absence of any exclusion guidance keep 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 both parameters are undocumented in the schema. The description implies the query is a topical question but never mentions the 'limit' parameter, its default, or what it controls, leaving a real gap for an agent tuning result count.

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 ('semantically search') and resource ('Sortition knowledge base'), and enumerates the topic domain it covers. It does not explicitly differentiate itself from siblings like get_document_page or list_documents, but the purpose is 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?

Explicitly says 'Use this for questions about sortition, citizens' assemblies, citizens' chambers, democratic institutions and related reforms,' giving clear context for invocation. It stops short of naming when-not to use it or which sibling to prefer for non-topical lookups.

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