run_saved_filter

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that: pagination behavior, support for sorting, and the caveat that orderBy is configured externally in Capsule's web UI. This meaningfully informs the agent about what the tool can and cannot do.

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 operation, followed by a targeted explanation of the saved-filter versus ad-hoc-filter difference. Every clause earns its place, and it remains succinct despite covering a subtle sorting distinction.

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?

It tells the agent what the tool does, when to use it, why it matters (sort support), and how to find the required id (via list_saved_filters). The embed options and entity enum are supplied in the schema, and no output schema exists, so the description provides complete enough context for the agent to invoke this tool 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?

The schema already covers id, entity, and embed, but page and perPage have no descriptions. The description only mentions 'paginated' broadly, without explaining pagination parameter ranges or semantics. With 60% schema description coverage, the description contributes some contextual value but does not fully compensate for the missing perPage/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 opens with a clear verb and target: 'Run a saved filter by id and return its results, paginated.' It also immediately distinguishes this from filter_parties / filter_opportunities / filter_projects, making the tool's exact role obvious to an agent.

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

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

It explicitly tells the agent when the tool is preferable: when sorting is needed and a saved filter exists. It names the alternatives and why they fail ('CANNOT sort'), and gives the clear prerequisite call: 'use list_saved_filters first to find one.'

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