feat(tools): Add feasible/annotated tool filtering based on agent-state predicates

[yashhzd]

Summary

Closes #148.

Adds support for conditionally filtering tools based on agent-state predicates, so reasoning strategies can present only feasible tools to the LLM (or annotate infeasible ones for planner awareness).

Changes

@tool(requires=...) decorator parameter

• New optional requires keyword on @tool: a callable (agent) -> bool that returns True when the tool is usable by the given agent.
• The predicate is stored as fn.__tool_requires__ on the decorated function.

ToolManager methods

• _is_tool_feasible(fn, agent) — checks the __tool_requires__ predicate; returns True when no predicate is set or when it passes, False on failure or exception.
• get_feasible_tools_schema(agent, selected_tools=None) — returns schemas only for tools whose preconditions are satisfied.
• get_annotated_tools_schema(agent, selected_tools=None) — returns all tool schemas with added available (bool) and unavailable_reason (str | None) keys, so planners can reason about currently-infeasible tools.

Built-in tool predicates

• _has_grid_and_position(agent) — applied to move_one_step and teleport_to_location.
• _has_other_agents(agent) — applied to speak_to.

Tests

• 8 new tests in tests/test_tools/test_feasible_tools.py covering:
  • Filtering infeasible tools
  • Tools without requires always included
  • Predicate receives correct agent state
  • selected_tools interaction
  • Exception in predicate treated as infeasible
  • Annotated schema correctness (available, unavailable_reason)

Backward Compatibility

• requires defaults to None, so all existing @tool decorations are unaffected.
• get_all_tools_schema() remains unchanged; the new methods are additive.
• Reasoning strategies can adopt the new methods at their own pace.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.15%. Comparing base (4c0549e) to head (caf2fe6).
⚠️ Report is 19 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #168      +/-   ##
==========================================
+ Coverage   90.08%   91.15%   +1.06%     
==========================================
  Files          19       19              
  Lines        1503     1582      +79     
==========================================
+ Hits         1354     1442      +88     
+ Misses        149      140       -9     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6d19e8c3-47c3-4214-91df-f58f5b57ed82

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}